From 3fb7b3ff1aea9e9f0c43f42d544be544aa91300e Mon Sep 17 00:00:00 2001 From: James Lu Date: Sat, 3 Oct 2015 16:39:52 -0700 Subject: [PATCH] Doc updates: +using-utils.md stub; update autogenerated references for protocols/inspircd, utils --- docs/technical/README.md | 2 +- docs/technical/inspircd.html | 107 +++++++++------- docs/technical/using-utils.md | 1 + docs/technical/utils.html | 233 ++++++++++++++++++++++++++++++++++ 4 files changed, 296 insertions(+), 47 deletions(-) create mode 100644 docs/technical/using-utils.md create mode 100644 docs/technical/utils.html diff --git a/docs/technical/README.md b/docs/technical/README.md index bb99e53..40a48a0 100644 --- a/docs/technical/README.md +++ b/docs/technical/README.md @@ -18,6 +18,6 @@ PyLink is an a modular, plugin-based IRC PseudoService framework. It uses swappa #### Future topics (not yet available) +- [Using PyLink's utils module](using-utils.md) - [PyLink hooks reference](hooks-reference.md) - [Writing tests for PyLink modules](writing-tests.md) -- [Using PyLink's utils module](using-utils.md) diff --git a/docs/technical/inspircd.html b/docs/technical/inspircd.html index 4f01b32..6bb13dc 100644 --- a/docs/technical/inspircd.html +++ b/docs/technical/inspircd.html @@ -74,9 +74,11 @@ For InspIRCd, the only ENCAP command we handl
handle_endburst(self, numeric, command, args)
ENDBURST handler; sends a hook with empty contents.
-
handle_events(self, data)
Event handler for the InspIRCd protocol. This passes most commands to
-the various handle_ABCD() functions elsewhere in this module, but also
-handles commands sent in the initial server linking phase.
+
handle_events(self, data)
Event handler for the InspIRCd protocol.
+ 
+This passes most commands to the various handle_ABCD() functions
+elsewhere in this module, but also handles commands sent in the
+initial server linking phase.
handle_fhost(self, numeric, command, args)
Handles FHOST, used for denoting hostname changes.
@@ -94,6 +96,8 @@ handles commands sent in the initial server l
handle_invite(self, numeric, command, args)
Handles incoming INVITEs.
+
handle_mode(self, numeric, command, args)
Handles incoming user mode changes.
+
handle_opertype(self, numeric, command, args)
Handles incoming OPERTYPE, which is used to denote an oper up.
 
This calls the internal hook PYLINK_CLIENT_OPERED, sets the internal
@@ -101,9 +105,11 @@ opertype of the client, and assumes setting u
handle_ping(self, source, command, args)
Handles incoming PING commands, so we don't time out.
-
handle_pong(self, source, command, args)
Handles incoming PONG commands. This is used to keep track of whether
-the uplink is alive by the Irc() internals - a server that fails to reply
-to our PINGs eventually times out and is disconnected.
+
handle_pong(self, source, command, args)
Handles incoming PONG commands.
+ 
+This is used to keep track of whether the uplink is alive by the Irc()
+internals - a server that fails to reply to our PINGs eventually
+times out and is disconnected.
handle_server(self, numeric, command, args)
Handles incoming SERVER commands (introduction of servers).
@@ -111,7 +117,7 @@ to our PINGs eventually times out and is 
inviteClient(self, numeric, target, channel)
Sends an INVITE from a PyLink client..
-
joinClient(self, client, channel)
Joins an internal spawned client <client> to a channel.
+
joinClient(self, client, channel)
Joins a PyLink client to a channel.
killClient(self, numeric, target, reason)
Sends a kill from a PyLink client.
@@ -119,13 +125,13 @@ to our PINGs eventually times out and is 
knockClient(self, numeric, target, text)
Sends a KNOCK from a PyLink client.
-
modeClient(self, numeric, target, modes, ts=None)
Sends modes from a PyLink client. <modes> should be
+
modeClient(self, numeric, target, modes, ts=None)
Sends mode changes from a PyLink client. <modes> should be
a list of (mode, arg) tuples, i.e. the format of utils.parseModes() output.
-
modeServer(self, numeric, target, modes, ts=None)
Sends modes from a PyLink server. <list of modes> should be
+
modeServer(self, numeric, target, modes, ts=None)
Sends mode changes from a PyLink server. <list of modes> should be
a list of (mode, arg) tuples, i.e. the format of utils.parseModes() output.
-
numericServer(self, source, numeric, text)
+
numericServer(self, source, numeric, target, text)
pingServer(self, source=None, target=None)
Sends a PING to a target server. Periodic PINGs are sent to our uplink
automatically by the Irc() internals; plugins shouldn't have to use this.
@@ -140,16 +146,19 @@ Example uses:
    sjoinServer('100', '#test', [('', '100AAABBC'), ('qo', 100AAABBB'), ('h', '100AAADDD')])
    sjoinServer(self.irc.sid, '#test', [('o', self.irc.pseudoclient.uid)])
-
spawnClient(self, nick, ident='null', host='null', realhost=None, modes=set(), server=None, ip='0.0.0.0', realname=None, ts=None, opertype=None)
Spawns a client with nick <nick> on the given IRC connection.
+
spawnClient(self, nick, ident='null', host='null', realhost=None, modes=set(), server=None, ip='0.0.0.0', realname=None, ts=None, opertype=None, manipulatable=False)
Spawns a client with nick <nick> on the given IRC connection.
 
Note: No nick collision / valid nickname checks are done here; it is
up to plugins to make sure they don't introduce anything invalid.
-
spawnServer(self, name, sid=None, uplink=None, desc=None)
Spawns a server off a PyLink server.
+
spawnServer(self, name, sid=None, uplink=None, desc=None)
Spawns a server off a PyLink server. desc (server description)
+defaults to the one in the config. uplink defaults to the main PyLink
+server, and sid (the server ID) is automatically generated if not
+given.
squitServer(self, source, target, text='No reason given')
SQUITs a PyLink server.
-
topicServer(self, numeric, target, text)
Sends a burst topic from a PyLink server. This is usally used on burst.
+
topicServer(self, numeric, target, text)
Sends a topic change from a PyLink server. This is usually used on burst.
updateClient(self, numeric, field, text)
Updates the ident, host, or realname of a PyLink client.
@@ -161,9 +170,6 @@ Methods inherited from ts6_common.TS6B
handle_kill(self, source, command, args)
Handles incoming KILLs.
-
handle_mode(self, numeric, command, args)
Handles incoming user mode changes. For channel mode changes,
-TMODE (TS6/charybdis) and FMODE (InspIRCd) are used instead.
-
handle_nick(self, numeric, command, args)
Handles incoming NICK changes.
handle_notice = handle_privmsg(self, source, command, args)
Handles incoming PRIVMSG/NOTICE.
@@ -172,7 +178,7 @@ TMODE (TS6/charybdis) and FMODE (InspIRCd) are use
handle_privmsg(self, source, command, args)
Handles incoming PRIVMSG/NOTICE.
-
handle_quit(self, numeric, command, args)
Handles incoming QUITs.
+
handle_quit(self, numeric, command, args)
Handles incoming QUIT commands.
handle_save(self, numeric, command, args)
Handles incoming SAVE messages, used to handle nick collisions.
@@ -191,9 +197,6 @@ TB (TS6/charybdis) and FTOPIC (InspIRCd) are used&
noticeClient(self, numeric, target, text)
Sends a NOTICE from a PyLink client.
-
parseArgs(self, args)
Parses a string of RFC1459-style arguments split into a list, where ":" may
-be used for multi-word arguments that last until the end of a line.
-
parseTS6Args(self, args)
Similar to parseArgs(), but stripping leading colons from the first argument
of a line (usually the sender field).
@@ -201,10 +204,15 @@ of a line (usually the sender field).
quitClient(self, numeric, reason)
Quits a PyLink client.
-
removeClient(self, numeric)
Internal function to remove a client from our internal state.
-
topicClient(self, numeric, target, text)
Sends a TOPIC change from a PyLink client.
+
+Methods inherited from classes.Protocol:
+
parseArgs(self, args)
Parses a string of RFC1459-style arguments split into a list, where ":" may
+be used for multi-word arguments that last until the end of a line.
+ +
removeClient(self, numeric)
Internal function to remove a client from our internal state.
+
Data descriptors inherited from classes.Protocol:
__dict__
@@ -245,9 +253,11 @@ For InspIRCd, the only ENCAP command we handl
handle_endburst(self, numeric, command, args)
ENDBURST handler; sends a hook with empty contents.
-
handle_events(self, data)
Event handler for the InspIRCd protocol. This passes most commands to
-the various handle_ABCD() functions elsewhere in this module, but also
-handles commands sent in the initial server linking phase.
+
handle_events(self, data)
Event handler for the InspIRCd protocol.
+ 
+This passes most commands to the various handle_ABCD() functions
+elsewhere in this module, but also handles commands sent in the
+initial server linking phase.
handle_fhost(self, numeric, command, args)
Handles FHOST, used for denoting hostname changes.
@@ -265,6 +275,8 @@ handles commands sent in the initial server l
handle_invite(self, numeric, command, args)
Handles incoming INVITEs.
+
handle_mode(self, numeric, command, args)
Handles incoming user mode changes.
+
handle_opertype(self, numeric, command, args)
Handles incoming OPERTYPE, which is used to denote an oper up.
 
This calls the internal hook PYLINK_CLIENT_OPERED, sets the internal
@@ -272,9 +284,11 @@ opertype of the client, and assumes setting u
handle_ping(self, source, command, args)
Handles incoming PING commands, so we don't time out.
-
handle_pong(self, source, command, args)
Handles incoming PONG commands. This is used to keep track of whether
-the uplink is alive by the Irc() internals - a server that fails to reply
-to our PINGs eventually times out and is disconnected.
+
handle_pong(self, source, command, args)
Handles incoming PONG commands.
+ 
+This is used to keep track of whether the uplink is alive by the Irc()
+internals - a server that fails to reply to our PINGs eventually
+times out and is disconnected.
handle_server(self, numeric, command, args)
Handles incoming SERVER commands (introduction of servers).
@@ -282,7 +296,7 @@ to our PINGs eventually times out and is 
inviteClient(self, numeric, target, channel)
Sends an INVITE from a PyLink client..
-
joinClient(self, client, channel)
Joins an internal spawned client <client> to a channel.
+
joinClient(self, client, channel)
Joins a PyLink client to a channel.
killClient(self, numeric, target, reason)
Sends a kill from a PyLink client.
@@ -290,13 +304,13 @@ to our PINGs eventually times out and is 
knockClient(self, numeric, target, text)
Sends a KNOCK from a PyLink client.
-
modeClient(self, numeric, target, modes, ts=None)
Sends modes from a PyLink client. <modes> should be
+
modeClient(self, numeric, target, modes, ts=None)
Sends mode changes from a PyLink client. <modes> should be
a list of (mode, arg) tuples, i.e. the format of utils.parseModes() output.
-
modeServer(self, numeric, target, modes, ts=None)
Sends modes from a PyLink server. <list of modes> should be
+
modeServer(self, numeric, target, modes, ts=None)
Sends mode changes from a PyLink server. <list of modes> should be
a list of (mode, arg) tuples, i.e. the format of utils.parseModes() output.
-
numericServer(self, source, numeric, text)
+
numericServer(self, source, numeric, target, text)
pingServer(self, source=None, target=None)
Sends a PING to a target server. Periodic PINGs are sent to our uplink
automatically by the Irc() internals; plugins shouldn't have to use this.
@@ -311,16 +325,19 @@ Example uses:
    sjoinServer('100', '#test', [('', '100AAABBC'), ('qo', 100AAABBB'), ('h', '100AAADDD')])
    sjoinServer(self.irc.sid, '#test', [('o', self.irc.pseudoclient.uid)])
-
spawnClient(self, nick, ident='null', host='null', realhost=None, modes=set(), server=None, ip='0.0.0.0', realname=None, ts=None, opertype=None)
Spawns a client with nick <nick> on the given IRC connection.
+
spawnClient(self, nick, ident='null', host='null', realhost=None, modes=set(), server=None, ip='0.0.0.0', realname=None, ts=None, opertype=None, manipulatable=False)
Spawns a client with nick <nick> on the given IRC connection.
 
Note: No nick collision / valid nickname checks are done here; it is
up to plugins to make sure they don't introduce anything invalid.
-
spawnServer(self, name, sid=None, uplink=None, desc=None)
Spawns a server off a PyLink server.
+
spawnServer(self, name, sid=None, uplink=None, desc=None)
Spawns a server off a PyLink server. desc (server description)
+defaults to the one in the config. uplink defaults to the main PyLink
+server, and sid (the server ID) is automatically generated if not
+given.
squitServer(self, source, target, text='No reason given')
SQUITs a PyLink server.
-
topicServer(self, numeric, target, text)
Sends a burst topic from a PyLink server. This is usally used on burst.
+
topicServer(self, numeric, target, text)
Sends a topic change from a PyLink server. This is usually used on burst.
updateClient(self, numeric, field, text)
Updates the ident, host, or realname of a PyLink client.
@@ -332,9 +349,6 @@ Methods inherited from ts6_common.TS6B
handle_kill(self, source, command, args)
Handles incoming KILLs.
-
handle_mode(self, numeric, command, args)
Handles incoming user mode changes. For channel mode changes,
-TMODE (TS6/charybdis) and FMODE (InspIRCd) are used instead.
-
handle_nick(self, numeric, command, args)
Handles incoming NICK changes.
handle_notice = handle_privmsg(self, source, command, args)
Handles incoming PRIVMSG/NOTICE.
@@ -343,7 +357,7 @@ TMODE (TS6/charybdis) and FMODE (InspIRCd) are use
handle_privmsg(self, source, command, args)
Handles incoming PRIVMSG/NOTICE.
-
handle_quit(self, numeric, command, args)
Handles incoming QUITs.
+
handle_quit(self, numeric, command, args)
Handles incoming QUIT commands.
handle_save(self, numeric, command, args)
Handles incoming SAVE messages, used to handle nick collisions.
@@ -362,9 +376,6 @@ TB (TS6/charybdis) and FTOPIC (InspIRCd) are used&
noticeClient(self, numeric, target, text)
Sends a NOTICE from a PyLink client.
-
parseArgs(self, args)
Parses a string of RFC1459-style arguments split into a list, where ":" may
-be used for multi-word arguments that last until the end of a line.
-
parseTS6Args(self, args)
Similar to parseArgs(), but stripping leading colons from the first argument
of a line (usually the sender field).
@@ -372,10 +383,15 @@ of a line (usually the sender field).
quitClient(self, numeric, reason)
Quits a PyLink client.
-
removeClient(self, numeric)
Internal function to remove a client from our internal state.
-
topicClient(self, numeric, target, text)
Sends a TOPIC change from a PyLink client.
+
+Methods inherited from classes.Protocol:
+
parseArgs(self, args)
Parses a string of RFC1459-style arguments split into a list, where ":" may
+be used for multi-word arguments that last until the end of a line.
+ +
removeClient(self, numeric)
Internal function to remove a client from our internal state.
+
Data descriptors inherited from classes.Protocol:
__dict__
@@ -391,7 +407,6 @@ Data descriptors inherited from classes.Protocol Data         -conf = {'bot': {'loglevel': 'CRITICAL', 'nick': 'PyLink', 'realname': 'PyLink Service Client', 'serverdesc': 'PyLink unit tests', 'user': 'pylink'}, 'servers': defaultdict(<function <lambda> at 0x7f0dbb516c80>, {})}
-curdir = 'protocols'
+curdir = 'protocols'
log = <logging.RootLogger object> \ No newline at end of file diff --git a/docs/technical/using-utils.md b/docs/technical/using-utils.md new file mode 100644 index 0000000..2ea79ac --- /dev/null +++ b/docs/technical/using-utils.md @@ -0,0 +1 @@ +This page is under construction: see [utils.html ](utils.html) for autogenerated documentation for the utils module. diff --git a/docs/technical/utils.html b/docs/technical/utils.html new file mode 100644 index 0000000..32844c8 --- /dev/null +++ b/docs/technical/utils.html @@ -0,0 +1,233 @@ + +Python: module utils + + + + + +
 
+ 
utils		index
/home/gl/pylink/utils.py
+

+

+ + + + + +
 
+Modules
       
imp
+inspect
+		re
+string
+		world
+

+ + + + + +
 
+Classes
       
+
builtins.Exception(builtins.BaseException) +
+
+
NotAuthenticatedError +
+
+
builtins.object +
+
+
TS6SIDGenerator +
TS6UIDGenerator +
+
+
+

+ + + + + + + +
 
+class NotAuthenticatedError(builtins.Exception)
   # This is separate from classes.py to prevent import loops.
 
 
Method resolution order:
+
NotAuthenticatedError
+
builtins.Exception
+
builtins.BaseException
+
builtins.object
+
+
+Data descriptors defined here:
+
__weakref__
+
list of weak references to the object (if defined)
+
+
+Methods inherited from builtins.Exception:
+
__init__(self, /, *args, **kwargs)
Initialize self.  See help(type(self)) for accurate signature.
+ +
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.
+ +
+Methods inherited from builtins.BaseException:
+
__delattr__(self, name, /)
Implement delattr(self, name).
+ +
__getattribute__(self, name, /)
Return getattr(self, name).
+ +
__reduce__(...)
+ +
__repr__(self, /)
Return repr(self).
+ +
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
+ +
__setstate__(...)
+ +
__str__(self, /)
Return str(self).
+ +
with_traceback(...)
Exception.with_traceback(tb) --
+set self.__traceback__ to tb and return self.
+ +
+Data descriptors inherited from builtins.BaseException:
+
__cause__
+
exception cause
+
+
__context__
+
exception context
+
+
__dict__
+
+
__suppress_context__
+
+
__traceback__
+
+
args
+
+

+ + + + + + + +
 
+class TS6SIDGenerator(builtins.object)
   TS6 SID Generator. <query> is a 3 character string with any combination of
+uppercase letters, digits, and #'s. it must contain at least one #,
+which are used by the generator as a wildcard. On every next_sid() call,
+the first available wildcard character (from the right) will be
+incremented to generate the next SID.
+ 
+When there are no more available SIDs left (SIDs are not reused, only
+incremented), RuntimeError is raised.
+ 
+Example queries:
+    "1#A" would give: 10A, 11A, 12A ... 19A, 1AA, 1BA ... 1ZA (36 total results)
+    "#BQ" would give: 0BQ, 1BQ, 2BQ ... 9BQ (10 total results)
+    "6##" would give: 600, 601, 602, ... 60Y, 60Z, 610, 611, ... 6ZZ (1296 total results)
 
 Methods defined here:
+
__init__(self, irc)
+ +
increment(self, pos=2)
+ +
next_sid(self)
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class TS6UIDGenerator(builtins.object)
   TS6 UID Generator module, adapted from InspIRCd source
+https://github.com/inspircd/inspircd/blob/f449c6b296ab/src/server.cpp#L85-L156
 
 Methods defined here:
+
__init__(self, sid)
+ +
increment(self, pos=5)
+ +
next_uid(self)
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + +
 
+Functions
       
add_cmd(func, name=None)
+
add_hook(func, command)
Add a hook <func> for command <command>.
+
applyModes(irc, target, changedmodes)
Takes a list of parsed IRC modes, and applies them on the given target.
+ 
+The target can be either a channel or a user; this is handled automatically.
+
checkAuthenticated(irc, uid, allowAuthed=True, allowOper=True)
Checks whetherthe given user has operator status on PyLink, raising
+NotAuthenticatedError and logging the access denial if not.
+
clientToServer(irc, numeric)
Finds the SID of the server a user is on.
+
getHostmask(irc, user)
Gets the hostmask of the given user, if present.
+
getProtoModule(protoname)
Imports and returns the protocol module requested.
+
isChannel(s)
Checks whether the string given is a valid channel name.
+
isHostmask(text)
Returns whether the given text is a valid hostmask.
+
isInternalClient(irc, numeric)
Checks whether the given numeric is a PyLink Client,
+returning the SID of the server it's on if so.
+
isInternalServer(irc, sid)
Returns whether the given SID is an internal PyLink server.
+
isManipulatableClient(irc, uid)
Returns whether the given user is marked as an internal, manipulatable
+client. Usually, automatically spawned services clients should have this
+set True to prevent interactions with opers (like mode changes) from
+causing desyncs.
+
isNick(s, nicklen=None)
Checks whether the string given is a valid nick.
+
isOper(irc, uid, allowAuthed=True, allowOper=True)
Returns whether the given user has operator status on PyLink. This can be achieved
+by either identifying to PyLink as admin (if allowAuthed is True),
+or having user mode +o set (if allowOper is True). At least one of
+allowAuthed or allowOper must be True for this to give any meaningful
+results.
+
isServerName(s)
Checks whether the string given is a server name.
+
joinModes(modes)
Takes a list of (mode, arg) tuples in parseModes() format, and
+joins them into a string.
+ 
+See testJoinModes in tests/test_utils.py for some examples.
+
loadModuleFromFolder(name, folder)
Attempts an import of name from a specific folder, returning the resulting module.
+
nickToUid(irc, nick)
Returns the UID of a user named nick, if present.
+
parseModes(irc, target, args)
Parses a modestring list into a list of (mode, argument) tuples.
+['+mitl-o', '3', 'person'] => [('+m', None), ('+i', None), ('+t', None), ('+l', '3'), ('-o', 'person')]
+
reverseModes(irc, target, modes, oldobj=None)
Reverses/Inverts the mode string or mode list given.
+ 
+Optionally, an oldobj argument can be given to look at an earlier state of
+a channel/user object, e.g. for checking the op status of a mode setter
+before their modes are processed and added to the channel state.
+ 
+This function allows both mode strings or mode lists. Example uses:
+    "+mi-lk test => "-mi+lk test"
+    "mi-k test => "-mi+k test"
+    [('+m', None), ('+r', None), ('+l', '3'), ('-o', 'person')
+     => {('-m', None), ('-r', None), ('-l', None), ('+o', 'person')})
+    {('s', None), ('+o', 'whoever') => {('-s', None), ('-o', 'whoever')})
+
toLower(irc, text)
Returns a lowercase representation of text based on the IRC object's
+casemapping (rfc1459 or ascii).
+

+ + + + + +
 
+Data
       hostmaskRe = re.compile('^\\S+!\\S+@\\S+$')
+log = <logging.RootLogger object>
+ \ No newline at end of file