From a777cd21ba0bc4aed6cb87b8775ab80ee807ec04 Mon Sep 17 00:00:00 2001 From: Edward Powell Date: Fri, 31 May 2013 12:19:35 -0400 Subject: [PATCH] [docs] Clarify documentation for willie.write() --- docs/source/index.rst | 30 +++++++++++++++++------------- willie/irc.py | 42 ++++++++++++++++++++++-------------------- 2 files changed, 39 insertions(+), 33 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index e845a35f89..d37899bcc4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -217,20 +217,24 @@ The ``Willie`` class respectively. .. py:function:: write(args, text=None) - - Send a command to the server. In the simplest case, ``args`` is a list - containing just the command you wish to send, and ``text`` the argument - to that command {e.g. write(['JOIN'], '#channel')} - - More specifically, ``args`` will be joined together, separated by a - space. If text is given, it will be added preceeded by a space and a - colon (' :'). - + + Send a command to the server + + ``args`` is an iterable of strings, which are joined by spaces. + ``text`` is treated as though it were the final item in ``args``, but + is preceeded by a ``:``. This is a special case which means that + ``text``, unlike the items in ``args`` may contain spaces (though this + constraint is not checked by ``write``). + + In other words, both ``willie.write(('PRIVMSG',), 'Hello, world!')`` + and ``willie.write(('PRIVMSG', ':Hello, world!'))`` will send + ``PRIVMSG :Hello, world!`` to the server. + Newlines and carriage returns ('\\n' and '\\r') are removed before - sending. Additionally, if the joined ``args`` and ``text`` are more than - 510 characters, any remaining characters will not be sent. - - .. py:function:: msg(recipient, text) + sending. Additionally, if the message (after joining) is longer than + than 510 characters, any remaining characters will not be sent. + + .. py:function:: msg(recipient, text) Send a PRIVMSG of ``text`` to ``recipient``. If the same ``text`` was the message in 5 or more of the last 8 calls to ``msg``, ``'...'`` will diff --git a/willie/irc.py b/willie/irc.py index ad7f6e0890..b1469bb930 100644 --- a/willie/irc.py +++ b/willie/irc.py @@ -42,7 +42,7 @@ class Origin(object): def __init__(self, bot, source, args): self.hostmask = source - + #Split out the nick, user, and host from hostmask per the regex above. match = Origin.source.match(source or '') self.nick, self.user, self.host = match.groups() @@ -110,7 +110,7 @@ def __init__(self, config): """ self.voices = dict() """ - A dictionary mapping channels to a ``Nick`` list of their voices, half-ops + A dictionary mapping channels to a ``Nick`` list of their voices, half-ops and ops. """ @@ -134,7 +134,7 @@ def log_raw(self, line, prefix): os._exit(1) f = codecs.open(os.path.join(self.config.core.logdir, 'raw.log'), 'a', encoding='utf-8') - f.write(prefix+unicode(time.time()) + "\t") + f.write(prefix + unicode(time.time()) + "\t") temp = line.replace('\n', '') f.write(temp) @@ -149,19 +149,21 @@ def safe(self, string): string = unicode(string, encoding='utf8') return string - def write(self, args, text=None): - """ - Send a command to the server. In the simplest case, ``args`` is a list - containing just the command you wish to send, and ``text`` the argument - to that command {e.g. write(['JOIN'], '#channel')} + """Send a command to the server + + ``args`` is an iterable of strings, which are joined by spaces. + ``text`` is treated as though it were the final item in ``args``, but + is preceeded by a ``:``. This is a special case which means that + ``text``, unlike the items in ``args`` may contain spaces (though this + constraint is not checked by ``write``). - More specifically, ``args`` will be joined together, separated by a - space. If text is given, it will be added preceeded by a space and a - colon (' :'). + In other words, both ``willie.write(('PRIVMSG',), 'Hello, world!')`` + and ``willie.write(('PRIVMSG', ':Hello, world!'))`` will send + ``PRIVMSG :Hello, world!`` to the server. Newlines and carriage returns ('\\n' and '\\r') are removed before - sending. Additionally, if the joined ``args`` and ``text`` are more + sending. Additionally, if the message (after joining) is longer than than 510 characters, any remaining characters will not be sent. """ args = [self.safe(arg) for arg in args] @@ -294,7 +296,7 @@ def handle_connect(self): self.write(('USER', self.user, '+iw', self.nick), self.name) stderr('Connected.') - self.last_ping_time = datetime.now(); + self.last_ping_time = datetime.now() timeout_check_thread = threading.Thread(target=self._timeout_check) timeout_check_thread.start() ping_thread = threading.Thread(target=self._send_ping) @@ -305,15 +307,15 @@ def _timeout_check(self): if (datetime.now() - self.last_ping_time).seconds > int(self.config.timeout): stderr('Ping timeout reached after %s seconds, closing connection' % self.config.timeout) self.handle_close() - break; + break else: time.sleep(int(self.config.timeout)) def _send_ping(self): while True: - if (datetime.now() - self.last_ping_time).seconds > int(self.config.timeout)/2: + if (datetime.now() - self.last_ping_time).seconds > int(self.config.timeout) / 2: self.write(('PING', self.config.host)) - time.sleep(int(self.config.timeout)/2) + time.sleep(int(self.config.timeout) / 2) def _ssl_send(self, data): """ Replacement for self.send() during SSL connections. """ @@ -366,7 +368,7 @@ def collect_incoming_data(self, data): except: # Discard line if encoding is unknown return - + if data: self.log_raw(data, '<<') self.buffer += data @@ -381,7 +383,7 @@ def found_terminator(self): source, line = line[1:].split(' ', 1) else: source = None - + if ' :' in line: argstr, text = line.split(' :', 1) args = argstr.split() @@ -492,8 +494,8 @@ def handle_error(self): stderr(trace) self.debug("core", 'Fatal error in core, please review exception log', 'always') - logfile = codecs.open(os.path.join(self.config.logdir, - 'exceptions.log'), 'a', encoding='utf-8') # TODO: make not + logfile = codecs.open(os.path.join(self.config.logdir, 'exceptions.log'), + 'a', encoding='utf-8') # TODO: make not # hardcoded logfile.write('Fatal error in core, handle_error() was called\n') logfile.write('last raw line was %s' % self.raw)