From 0af1c7fe9a03be34e14ae8ecc332f6d1fa168511 Mon Sep 17 00:00:00 2001 From: mathieui Date: Mon, 21 May 2012 02:14:25 +0200 Subject: Docstrings, and small cleanup --- src/connection.py | 3 +++ src/contact.py | 12 ++++++--- src/core.py | 72 +++++++++++++++++++++++++++++++++++++-------------- src/events.py | 6 +++-- src/plugin.py | 14 ++++++++++ src/plugin_manager.py | 68 +++++++++++++++++++++++++++++++++++++++++------- src/roster.py | 51 ++++++++++++++++++++---------------- src/tabs.py | 7 ++++- src/xhtml.py | 5 ++-- 9 files changed, 178 insertions(+), 60 deletions(-) diff --git a/src/connection.py b/src/connection.py index ce300261..3f61b8cf 100644 --- a/src/connection.py +++ b/src/connection.py @@ -97,5 +97,8 @@ class Connection(sleekxmpp.ClientXMPP): sleekxmpp.ClientXMPP.send_raw(self, data, now, reconnect) class MatchAll(sleekxmpp.xmlstream.matcher.base.MatcherBase): + """ + Callback to retrieve all the stanzas for the XML tab + """ def match(self, xml): return True diff --git a/src/contact.py b/src/contact.py index 69dfb984..8d3b2bdf 100644 --- a/src/contact.py +++ b/src/contact.py @@ -7,13 +7,13 @@ """ Defines the Resource and Contact classes, which are used in -the roster +the roster. """ import logging log = logging.getLogger(__name__) -from sleekxmpp.xmlstream.stanzabase import JID +from sleekxmpp.xmlstream import JID class Resource(object): """ @@ -21,6 +21,9 @@ class Resource(object): It's a precise resource. """ def __init__(self, jid, data): + """ + data: the dict to use as a source + """ self._jid = JID(jid) # Full jid self._data = data @@ -63,11 +66,12 @@ class Contact(object): @property def bare_jid(self): - """The bare_jid or the contact""" + """The bare jid of the contact""" return self.__item.jid @property def name(self): + """The name of the contact or an empty string.""" return self.__item['name'] or '' @property @@ -77,6 +81,7 @@ class Contact(object): @property def pending_in(self): + """We received a subscribe stanza from this contact.""" return self.__item['pending_in'] @pending_in.setter @@ -85,6 +90,7 @@ class Contact(object): @property def pending_out(self): + """We sent a subscribe stanza to this contact.""" return self.__item['pending_out'] @pending_out.setter diff --git a/src/core.py b/src/core.py index 4cf0a7d4..419ba38f 100644 --- a/src/core.py +++ b/src/core.py @@ -43,7 +43,7 @@ import bookmark from plugin_manager import PluginManager from data_forms import DataFormsTab -from config import config, options +from config import config from logger import logger from roster import roster from contact import Contact, Resource @@ -100,22 +100,19 @@ Status = collections.namedtuple('Status', 'show message') class Core(object): """ - User interface using ncurses + “Main” class of poezion """ def __init__(self): # All uncaught exception are given to this callback, instead # of being displayed on the screen and exiting the program. + sys.excepthook = self.on_exception self.connection_time = time.time() self.status = Status(show=None, message='') - sys.excepthook = self.on_exception self.running = True - self.events = events.EventHandler() self.xmpp = singleton.Singleton(connection.Connection) self.xmpp.core = self roster.set_node(self.xmpp.client_roster) - roster.set_mucs(self.xmpp.plugin['xep_0045'].rooms) - roster.set_self_jid(self.xmpp.boundjid.bare) self.paused = False self.remote_fifo = None # a unique buffer used to store global informations @@ -124,13 +121,21 @@ class Core(object): self.information_buffer = TextBuffer() self.information_win_size = config.get('info_win_height', 2, 'var') self.information_win = windows.TextWin(300) - self.xml_buffer = TextBuffer() - self.tab_win = windows.GlobalInfoBar() self.information_buffer.add_window(self.information_win) - self.tabs = [] + + self.tab_win = windows.GlobalInfoBar() + # Number of xml tabs opened, used to avoid useless memory consumption self.xml_tabs = 0 + self.xml_buffer = TextBuffer() + + self.tabs = [] self.previous_tab_nb = 0 + self.own_nick = config.get('default_nick', '') or self.xmpp.boundjid.user + + self.plugin_manager = PluginManager(self) + self.events = events.EventHandler() + # global commands, available from all tabs # a command is tuple of the form: # (the function executing the command. Takes a string as argument, @@ -138,7 +143,6 @@ class Core(object): # a completion function, taking a Input as argument. Can be None) # The completion function should return True if a completion was # made ; False otherwise - self.plugin_manager = PluginManager(self) self.commands = { 'help': (self.command_help, '\_o< KOIN KOIN KOIN', self.completion_help), 'join': (self.command_join, _("Usage: /join [room_name][@server][/nick] [password]\nJoin: Join the specified room. You can specify a nickname after a slash (/). If no nickname is specified, you will use the default_nick in the configuration file. You can omit the room name: you will then join the room you\'re looking at (useful if you were kicked). You can also provide a room_name without specifying a server, the server of the room you're currently in will be used. You can also provide a password to join the room.\nExamples:\n/join room@server.tld\n/join room@server.tld/John\n/join room2\n/join /me_again\n/join\n/join room@server.tld/my_nick password\n/join / password"), self.completion_join), @@ -171,13 +175,16 @@ class Core(object): 'bookmarks': (self.command_bookmarks, _("Usage: /bookmarks\nBookmarks: Show the current bookmarks."), None), 'remove_bookmark': (self.command_remove_bookmark, _("Usage: /remove_bookmark [jid]\nRemove Bookmark: Remove the specified bookmark, or the bookmark on the current tab, if any."), self.completion_remove_bookmark), 'xml_tab': (self.command_xml_tab, _("Usage: /xml_tab\nXML Tab: Open an XML tab."), None), - } + } + # We are invisible if config.get('send_initial_presence', 'true').lower() == 'false': del self.commands['status'] del self.commands['show'] self.key_func = KeyDict() + # Key bindings associated with handlers + # and pseudo-keys used to map actions below. key_func = { "KEY_PPAGE": self.scroll_page_up, "KEY_NPAGE": self.scroll_page_down, @@ -292,6 +299,9 @@ class Core(object): log.debug("Config reloaded.") def autoload_plugins(self): + """ + Load the plugins on startup. + """ plugins = config.get('plugins_autoload', '') for plugin in plugins.split(): self.plugin_manager.load(plugin) @@ -363,18 +373,24 @@ class Core(object): tabs.Tab.height - 1 - self.information_win_size - tabs.Tab.tab_win_height(), 0) def outgoing_stanza(self, stanza): + """ + We are sending a new stanza, write it in the xml buffer if needed. + """ if self.xml_tabs: self.add_message_to_text_buffer(self.xml_buffer, '\x191}<--\x19o %s' % stanza) - if isinstance(self.current_tab(), tabs.XMLTab): - self.current_tab().refresh() - self.doupdate() + if isinstance(self.current_tab(), tabs.XMLTab): + self.current_tab().refresh() + self.doupdate() def incoming_stanza(self, stanza): + """ + We are receiving a new stanza, write it in the xml buffer if needed. + """ if self.xml_tabs: self.add_message_to_text_buffer(self.xml_buffer, '\x192}-->\x19o %s' % stanza) - if isinstance(self.current_tab(), tabs.XMLTab): - self.current_tab().refresh() - self.doupdate() + if isinstance(self.current_tab(), tabs.XMLTab): + self.current_tab().refresh() + self.doupdate() def command_xml_tab(self, arg=''): """/xml_tab""" @@ -611,6 +627,9 @@ class Core(object): return True def on_chatstate_private_conversation(self, message, state): + """ + Chatstate received in a private conversation from a MUC + """ tab = self.get_tab_by_name(message['from'].full, tabs.PrivateTab) if not tab: return @@ -622,6 +641,9 @@ class Core(object): return True def on_chatstate_groupchat_conversation(self, message, state): + """ + Chatstate received in a MUC + """ nick = message['mucnick'] room_from = message.getMucroom() tab = self.get_tab_by_name(room_from, tabs.MucTab) @@ -634,6 +656,9 @@ class Core(object): self.doupdate() def on_attention(self, message): + """ + Attention probe received. + """ jid_from = message['from'] self.information('%s requests your attention!' % jid_from, 'Info') for tab in self.tabs: @@ -1319,7 +1344,7 @@ class Core(object): def open_conversation_window(self, jid, focus=True): """ - open a new conversation tab and focus it if needed + Open a new conversation tab and focus it if needed """ for tab in self.tabs: # if the room exists, focus it and return if isinstance(tab, tabs.ConversationTab): @@ -1335,6 +1360,9 @@ class Core(object): return new_tab def open_private_window(self, room_name, user_nick, focus=True): + """ + Open a Private conversation in a MUC and focus if needed. + """ complete_jid = room_name+'/'+user_nick for tab in self.tabs: # if the room exists, focus it and return if isinstance(tab, tabs.PrivateTab): @@ -1358,7 +1386,7 @@ class Core(object): def on_groupchat_subject(self, message): """ - triggered when the topic is changed + Triggered when the topic is changed. """ nick_from = message['mucnick'] room_from = message.getMucroom() @@ -1503,6 +1531,7 @@ class Core(object): self.information(msg, 'Help') def completion_help(self, the_input): + """Completion for /help.""" commands = list(self.commands.keys()) + list(self.current_tab().commands.keys()) return the_input.auto_completion(commands, ' ', quotify=False) @@ -1760,6 +1789,7 @@ class Core(object): self.refresh_window() def completion_win(self, the_input): + """Completion for /win""" l = [JID(tab.get_name()).user for tab in self.tabs] l.remove('') return the_input.auto_completion(l, ' ', quotify=False) @@ -1878,6 +1908,7 @@ class Core(object): return the_input.auto_completion([jid for jid in roster.jids()], '', quotify=False) def completion_list(self, the_input): + """Completion for /list""" muc_serv_list = [] for tab in self.tabs: # TODO, also from an history if isinstance(tab, tabs.MucTab) and\ @@ -2380,13 +2411,16 @@ class Core(object): self.refresh_window() def remove_timed_event(self, event): + """Remove an existing timed event""" if event and event in self.timed_events: self.timed_events.remove(event) def add_timed_event(self, event): + """Add a new timed event""" self.timed_events.add(event) def check_timed_events(self): + """Check for the execution of timed events""" now = datetime.now() for event in self.timed_events: if event.has_timed_out(now): diff --git a/src/events.py b/src/events.py index e66c5ee5..6ca8296d 100644 --- a/src/events.py +++ b/src/events.py @@ -5,7 +5,9 @@ # it under the terms of the zlib license. See the COPYING file. """ -Defines the EventHandler class +Defines the EventHandler class. +The list of available events is here: +http://poezio.eu/doc/en/plugins.html#_poezio_events """ import logging @@ -16,7 +18,7 @@ class EventHandler(object): A class keeping a list of possible events that are triggered by poezio. You (a plugin for example) can add an event handler associated with an event name, and whenever that event is triggered, - the callback is called + the callback is called. """ def __init__(self): self.events = { diff --git a/src/plugin.py b/src/plugin.py index f35bdab1..bd5c88be 100644 --- a/src/plugin.py +++ b/src/plugin.py @@ -1,3 +1,8 @@ +""" +Define the PluginConfig and Plugin classes, plus the SafetyMetaclass. +These are used in the plugin system added in poezio 0.7.5 +(see plugin_manager.py) +""" import os from configparser import RawConfigParser import config @@ -5,6 +10,11 @@ import inspect import traceback class PluginConfig(config.Config): + """ + Plugin configuration object. + They are accessible inside the plugin with self.config + and behave like the core Config object. + """ def __init__(self, filename, module_name): self.file_name = filename self.module_name = module_name @@ -28,6 +38,10 @@ class PluginConfig(config.Config): self.add_section(self.module_name) def options(self, section=None): + """ + Return the options of the section + If no section is given, it defaults to the plugin name. + """ if not section: section = self.module_name if not self.has_section(section): diff --git a/src/plugin_manager.py b/src/plugin_manager.py index 40367052..32cb2c03 100644 --- a/src/plugin_manager.py +++ b/src/plugin_manager.py @@ -1,11 +1,19 @@ +""" +Plugin manager module. +Define the PluginManager class, the one that glues all the plugins and +the API together. Defines also a bunch of variables related to the +plugin env. +""" + import imp import os import sys -import tabs import logging -from config import config from gettext import gettext as _ +import tabs +from config import config + log = logging.getLogger(__name__) plugins_dir = config.get('plugins_dir', '') @@ -33,6 +41,11 @@ except OSError: sys.path.append(plugins_dir) class PluginManager(object): + """ + Plugin Manager + Contains all the references to the plugins + And keeps track of everything the plugin has done through the API. + """ def __init__(self, core): self.core = core self.modules = {} # module name -> module object @@ -44,6 +57,9 @@ class PluginManager(object): self.tab_keys = {} #module name → dict of tab types; tab type → list of keybinds (tuples) def load(self, name, notify=True): + """ + Load a plugin. + """ if name in self.plugins: self.unload(name) @@ -107,13 +123,30 @@ class PluginManager(object): log.debug("Could not unload plugin: \n%s", traceback.format_exc()) self.core.information("Could not unload plugin: %s" % e, 'Error') + def add_command(self, module_name, name, handler, help, completion=None): + """ + Add a global command. + """ + if name in self.core.commands: + raise Exception(_("Command '%s' already exists") % (name,)) + + commands = self.commands[module_name] + commands[name] = (handler, help, completion) + self.core.commands[name] = (handler, help, completion) + def del_command(self, module_name, name): + """ + Remove a global command added through add_command. + """ if name in self.commands[module_name]: del self.commands[module_name][name] if name in self.core.commands: del self.core.commands[name] def add_tab_command(self, module_name, tab_type, name, handler, help, completion=None): + """ + Add a command only for a type of Tab. + """ commands = self.tab_commands[module_name] t = tab_type.__name__ if name in tab_type.plugin_commands: @@ -127,6 +160,9 @@ class PluginManager(object): tab.update_commands() def del_tab_command(self, module_name, tab_type, name): + """ + Remove a command added through add_tab_command. + """ commands = self.tab_commands[module_name] t = tab_type.__name__ if not t in commands: @@ -140,6 +176,9 @@ class PluginManager(object): del tab.commands[name] def add_tab_key(self, module_name, tab_type, key, handler): + """ + Associate a key binding to a handler only for a type of Tab. + """ keys = self.tab_keys[module_name] t = tab_type.__name__ if key in tab_type.plugin_keys: @@ -153,6 +192,9 @@ class PluginManager(object): tab.update_keys() def del_tab_key(self, module_name, tab_type, key): + """ + Remove a key binding added through add_tab_key. + """ keys = self.tab_keys[module_name] t = tab_type.__name__ if not t in keys: @@ -166,6 +208,10 @@ class PluginManager(object): del tab.key_func[key] def add_key(self, module_name, key, handler): + """ + Associate a global key binding to a handler, except if it + already exists. + """ if key in self.core.key_func: raise Exception(_("Key '%s' already exists") % (key,)) keys = self.keys[module_name] @@ -173,20 +219,19 @@ class PluginManager(object): self.core.key_func[key] = handler def del_key(self, module_name, key): + """ + Remove a global key binding added by a plugin. + """ if key in self.keys[module_name]: del self.keys[module_name][key] if key in self.core.key_func: del self.core.commands[key] - def add_command(self, module_name, name, handler, help, completion=None): - if name in self.core.commands: - raise Exception(_("Command '%s' already exists") % (name,)) - - commands = self.commands[module_name] - commands[name] = (handler, help, completion) - self.core.commands[name] = (handler, help, completion) - def add_event_handler(self, module_name, event_name, handler, position=0): + """ + Add an event handler. If event_name isn’t in the event list, assume + it is a sleekxmpp event. + """ eh = self.event_handlers[module_name] eh.append((event_name, handler)) if event_name in self.core.events.events: @@ -195,6 +240,9 @@ class PluginManager(object): self.core.xmpp.add_event_handler(event_name, handler) def del_event_handler(self, module_name, event_name, handler): + """ + Remove an event handler if it exists. + """ if event_name in self.core.events.events: self.core.events.del_event_handler(None, handler) else: diff --git a/src/roster.py b/src/roster.py index e1251024..c86b33ac 100644 --- a/src/roster.py +++ b/src/roster.py @@ -19,6 +19,11 @@ from sleekxmpp.xmlstream.stanzabase import JID from sleekxmpp.exceptions import IqError class Roster(object): + """ + The proxy class to get the roster from SleekXMPP. + Adds a blacklist for the MUC domains (or else they would show here), + and caches Contact and RosterGroup objects. + """ # MUC domains to blacklist from the contacts roster blacklist = set() @@ -26,11 +31,8 @@ class Roster(object): def __init__(self): """ node: the RosterSingle from SleekXMPP - mucs: the dict from the SleekXMPP MUC plugin containing the joined mucs """ self.__node = None - self.__mucs = None - self.jid = None self.contact_filter = None # A tuple(function, *args) # function to filter contacts, # on search, for example @@ -41,19 +43,6 @@ class Roster(object): self.groups = {} self.contacts = {} - def set_node(self, value): - self.__node = value - - def set_mucs(self, value): - self.__mucs = value - - def set_self_jid(self, value): - self.jid = value - - def get_groups(self): - """Return a list of the RosterGroups""" - return [group for group in self.groups.values() if group] - def __getitem__(self, key): """Get a Contact from his bare JID""" key = JID(key).bare @@ -95,6 +84,19 @@ class Roster(object): """True if the bare jid is in the roster, false otherwise""" return JID(key).bare in self.jids() + @property + def jid(self): + """Our JID""" + return self.__node.jid + + def set_node(self, value): + """Set the SleekXMPP RosterSingle for our roster""" + self.__node = value + + def get_groups(self): + """Return a list of the RosterGroups""" + return [group for group in self.groups.values() if group] + def get_group(self, name): """Return a group or create it if not present""" if name in self.groups: @@ -126,6 +128,9 @@ class Roster(object): config.set_and_save('folded_roster_groups', folded_groups, 'var') def get_nb_connected_contacts(self): + """ + Get the number of connected contacts + """ n = 0 for contact in self: if contact.resources: @@ -206,7 +211,9 @@ class RosterGroup(object): It can be Friends/Family etc, but also can be Online/Offline or whatever """ - def __init__(self, name, contacts=[], folded=False): + def __init__(self, name, contacts=None, folded=False): + if not contacts: + contacts = [] self.contacts = set(contacts) self.name = name self.folded = folded # if the group content is to be shown @@ -219,6 +226,7 @@ class RosterGroup(object): return '' % (self.name, self.contacts) def __len__(self): + """Number of contacts in the group""" return len(self.contacts) def __contains__(self, contact): @@ -250,6 +258,7 @@ class RosterGroup(object): return sorted(contact_list, key=compare_contact, reverse=True) def toggle_folded(self): + """Fold/unfold the group in the roster""" self.folded = not self.folded if self.folded: if self.name not in roster.folded_groups: @@ -259,10 +268,8 @@ class RosterGroup(object): roster.folded_groups.remove(self.name) def get_nb_connected_contacts(self): - l = 0 - for contact in self.contacts.copy(): - if contact.resources: - l += 1 - return l + """Return the number of connected contacts""" + return len([1 for contact in self.contacts if contact.resources]) +# Shared roster object roster = Roster() diff --git a/src/tabs.py b/src/tabs.py index 4e1c5141..1b5c81e2 100644 --- a/src/tabs.py +++ b/src/tabs.py @@ -763,6 +763,7 @@ class MucTab(ChatTab): self.core.close_tab() def command_cycle(self, arg): + """/cycle [reason]""" if self.joined: muc.leave_groupchat(self.core.xmpp, self.get_name(), self.own_nick, arg) self.disconnect() @@ -897,7 +898,6 @@ class MucTab(ChatTab): color_other = get_theme().COLOR_USER_NONE[0] color_moderator = get_theme().COLOR_USER_MODERATOR[0] color_participant = get_theme().COLOR_USER_PARTICIPANT[0] - color_information = get_theme().COLOR_INFORMATION_TEXT[0] visitors, moderators, participants, others = [], [], [], [] aff = { 'owner': lambda: get_theme().CHAR_AFFILIATION_OWNER, @@ -940,6 +940,7 @@ class MucTab(ChatTab): return the_input.auto_completion([current_topic], '', quotify=False) def completion_quoted(self, the_input): + """Nick completion, but with quotes""" compare_users = lambda x: x.last_talked word_list = [user.nick for user in sorted(self.users, key=compare_users, reverse=True)\ if user.nick != self.own_nick] @@ -1020,6 +1021,10 @@ class MucTab(ChatTab): self.core.information('Could not set affiliation', 'Error') def command_say(self, line): + """ + /say + Or normal input + enter + """ needed = 'inactive' if self.inactive else 'active' msg = self.core.xmpp.make_message(self.get_name()) msg['type'] = 'groupchat' diff --git a/src/xhtml.py b/src/xhtml.py index 38ec690c..4d93a855 100644 --- a/src/xhtml.py +++ b/src/xhtml.py @@ -13,20 +13,19 @@ poezio colors to xhtml code """ import re -import subprocess import curses from sleekxmpp.xmlstream import ET import xml.sax.saxutils -from xml.etree.ElementTree import ElementTree - from sys import version_info from config import config import logging digits = '0123456789' # never trust the modules + +# HTML named colors colors = { 'aliceblue': 231, 'antiquewhite': 231, -- cgit v1.2.3