From d6bfc38ae3c8475ecb475ae7f95de63821d5e4ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Helleu?= Date: Sun, 11 May 2014 08:15:18 +0200 Subject: [PATCH] doc: fix pylint warnings in docgen.py --- doc/docgen.py | 321 ++++++++++++++++++++++++++------------------------ 1 file changed, 166 insertions(+), 155 deletions(-) diff --git a/doc/docgen.py b/doc/docgen.py index 2ebfd3b43..c2e8c262d 100644 --- a/doc/docgen.py +++ b/doc/docgen.py @@ -16,22 +16,24 @@ # along with this program. If not, see . # -# -# Documentation generator for WeeChat: build include files with commands, -# options, infos, infolists, hdata and completions for WeeChat core and -# plugins. -# -# Instructions to build config files yourself in WeeChat directories (replace -# all paths with your path to WeeChat): -# 1. run WeeChat and load this script, with following command: -# /python load ~/src/weechat/doc/docgen.py -# 2. change path to build in your doc/ directory: -# /set plugins.var.python.docgen.path "~/src/weechat/doc" -# 3. run docgen command: -# /docgen -# Note: it is recommended to load only this script when building doc. -# Files should be in ~/src/weechat/doc/xx/autogen/ (where xx is language). -# +""" +Documentation generator for WeeChat: build include files with commands, +options, infos, infolists, hdata and completions for WeeChat core and +plugins. + +Instructions to build config files yourself in WeeChat directories (replace +all paths with your path to WeeChat): + 1. run WeeChat and load this script, with following command: + /python load ~/src/weechat/doc/docgen.py + 2. change path to build in your doc/ directory: + /set plugins.var.python.docgen.path "~/src/weechat/doc" + 3. run docgen command: + /docgen +Note: it is recommended to load only this script when building doc. +Files should be in ~/src/weechat/doc/xx/autogen/ (where xx is language). +""" + +from __future__ import print_function SCRIPT_NAME = 'docgen' SCRIPT_AUTHOR = 'Sébastien Helleu ' @@ -41,14 +43,14 @@ SCRIPT_DESC = 'Documentation generator for WeeChat' SCRIPT_COMMAND = 'docgen' -import_ok = True +IMPORT_OK = True try: - import weechat + import weechat # pylint: disable=import-error except ImportError: print('This script must be run under WeeChat.') print('Get WeeChat now at: http://www.weechat.org/') - import_ok = False + IMPORT_OK = False try: import gettext @@ -59,7 +61,7 @@ try: from operator import itemgetter except ImportError as message: print('Missing package(s) for {0}: {1}'.format(SCRIPT_NAME, message)) - import_ok = False + IMPORT_OK = False # default path where doc files will be written (should be doc/ in sources # package tree) @@ -73,7 +75,7 @@ except ImportError as message: DEFAULT_PATH = '~/src/weechat/doc' # list of locales for which we want to build doc files to include -locale_list = ('en_US', 'fr_FR', 'it_IT', 'de_DE', 'ja_JP', 'pl_PL') +LOCALE_LIST = ('en_US', 'fr_FR', 'it_IT', 'de_DE', 'ja_JP', 'pl_PL') # all commands/options/.. of following plugins will produce a file # non-listed plugins will be ignored @@ -82,7 +84,7 @@ locale_list = ('en_US', 'fr_FR', 'it_IT', 'de_DE', 'ja_JP', 'pl_PL') # if plugin is listed without "c", that means plugin has only one command # /name (where "name" is name of plugin) # Note: we consider core is a plugin called "weechat" -plugin_list = { +PLUGIN_LIST = { 'sec': 'o', 'weechat': 'co', 'alias': '', @@ -105,29 +107,29 @@ plugin_list = { } # options to ignore -ignore_options = ( - 'aspell\.dict\..*', - 'aspell\.option\..*', - 'charset\.decode\..*', - 'charset\.encode\..*', - 'irc\.msgbuffer\..*', - 'irc\.ctcp\..*', - 'irc\.ignore\..*', - 'irc\.server\..*', - 'jabber\.server\..*', - 'logger\.level\..*', - 'logger\.mask\..*', - 'relay\.port\..*', - 'trigger\.trigger\..*', - 'weechat\.palette\..*', - 'weechat\.proxy\..*', - 'weechat\.bar\..*', - 'weechat\.debug\..*', - 'weechat\.notify\..*', +IGNORE_OPTIONS = ( + r'aspell\.dict\..*', + r'aspell\.option\..*', + r'charset\.decode\..*', + r'charset\.encode\..*', + r'irc\.msgbuffer\..*', + r'irc\.ctcp\..*', + r'irc\.ignore\..*', + r'irc\.server\..*', + r'jabber\.server\..*', + r'logger\.level\..*', + r'logger\.mask\..*', + r'relay\.port\..*', + r'trigger\.trigger\..*', + r'weechat\.palette\..*', + r'weechat\.proxy\..*', + r'weechat\.bar\..*', + r'weechat\.debug\..*', + r'weechat\.notify\..*', ) # completions to ignore -ignore_completions_items = ( +IGNORE_COMPLETIONS_ITEMS = ( 'docgen.*', 'jabber.*', 'weeget.*', @@ -138,14 +140,13 @@ def get_commands(): """ Get list of commands in a dict with 3 indexes: plugin, command, xxx. """ - global plugin_list commands = defaultdict(lambda: defaultdict(defaultdict)) infolist = weechat.infolist_get('hook', '', 'command') while weechat.infolist_next(infolist): plugin = weechat.infolist_string(infolist, 'plugin_name') or 'weechat' - if plugin in plugin_list: + if plugin in PLUGIN_LIST: command = weechat.infolist_string(infolist, 'command') - if command == plugin or 'c' in plugin_list[plugin]: + if command == plugin or 'c' in PLUGIN_LIST[plugin]: for key in ('description', 'args', 'args_description', 'completion'): commands[plugin][command][key] = \ @@ -159,15 +160,14 @@ def get_options(): Get list of config options in a dict with 4 indexes: config, section, option, xxx. """ - global plugin_list, ignore_options options = \ defaultdict(lambda: defaultdict(lambda: defaultdict(defaultdict))) infolist = weechat.infolist_get('option', '', '') while weechat.infolist_next(infolist): full_name = weechat.infolist_string(infolist, 'full_name') - if not re.search('|'.join(ignore_options), full_name): + if not re.search('|'.join(IGNORE_OPTIONS), full_name): config = weechat.infolist_string(infolist, 'config_name') - if config in plugin_list and 'o' in plugin_list[config]: + if config in PLUGIN_LIST and 'o' in PLUGIN_LIST[config]: section = weechat.infolist_string(infolist, 'section_name') option = weechat.infolist_string(infolist, 'option_name') for key in ('type', 'string_values', 'default_value', @@ -232,6 +232,7 @@ def get_infolists(): return infolists +# pylint: disable=too-many-locals def get_hdata(): """ Get list of hdata hooked by plugins in a dict with 3 indexes: @@ -266,15 +267,16 @@ def get_hdata(): var_hdata = ', hdata: "{0}"'.format(var_hdata) type_string = weechat.hdata_get_var_type_string(ptr_hdata, key) - d = {'__update_allowed': key} hdata2.append({'offset': var_offset, 'text': '\'{0}\' ({1})'.format(key, type_string), 'textlong': '\'{0}\' ({1}{2}{3})' ''.format(key, type_string, var_array_size, var_hdata), - 'update': weechat.hdata_update(ptr_hdata, - '', d)}) + 'update': weechat.hdata_update( + ptr_hdata, + '', + {'__update_allowed': key})}) hdata2 = sorted(hdata2, key=itemgetter('offset')) for item in hdata2: variables += '*** {0}\n'.format(item['textlong']) @@ -303,12 +305,11 @@ def get_completions(): Get list of completions hooked by plugins in a dict with 3 indexes: plugin, item, xxx. """ - global ignore_completions_items completions = defaultdict(lambda: defaultdict(defaultdict)) infolist = weechat.infolist_get('hook', '', 'completion') while weechat.infolist_next(infolist): completion_item = weechat.infolist_string(infolist, 'completion_item') - if not re.search('|'.join(ignore_completions_items), completion_item): + if not re.search('|'.join(IGNORE_COMPLETIONS_ITEMS), completion_item): plugin = weechat.infolist_string(infolist, 'plugin_name') or \ 'weechat' completions[plugin][completion_item]['description'] = \ @@ -340,12 +341,14 @@ def get_url_options(): def update_file(oldfile, newfile, num_files, num_files_updated, obj): """Update a doc file.""" try: - shaold = hashlib.sha224(open(oldfile, 'r').read()).hexdigest() - except: + with open(oldfile, 'r') as _file: + shaold = hashlib.sha224(_file.read()).hexdigest() + except IOError: shaold = '' try: - shanew = hashlib.sha224(open(newfile, 'r').read()).hexdigest() - except: + with open(newfile, 'r') as _file: + shanew = hashlib.sha224(_file.read()).hexdigest() + except IOError: shanew = '' if shaold != shanew: if os.path.exists(oldfile): @@ -362,13 +365,13 @@ def update_file(oldfile, newfile, num_files, num_files_updated, obj): num_files[obj] += 1 -def docgen_cmd_cb(data, buffer, args): +# pylint: disable=too-many-locals, too-many-branches, too-many-statements +def docgen_cmd_cb(data, buf, args): """Callback for /docgen command.""" - global locale_list if args: locales = args.split(' ') else: - locales = locale_list + locales = LOCALE_LIST commands = get_commands() options = get_options() infos = get_infos() @@ -387,6 +390,7 @@ def docgen_cmd_cb(data, buffer, args): num_files = defaultdict(int) num_files_updated = defaultdict(int) + # pylint: disable=undefined-variable translate = lambda s: (s and _(s)) or s escape = lambda s: s.replace('|', '\\|') @@ -395,10 +399,11 @@ def docgen_cmd_cb(data, buffer, args): if key != 'total2': num_files[key] = 0 num_files_updated[key] = 0 - t = gettext.translation('weechat', - weechat.info_get('weechat_localedir', ''), - languages=[locale + '.UTF-8'], fallback=True) - t.install() + trans = gettext.translation('weechat', + weechat.info_get('weechat_localedir', ''), + languages=[locale + '.UTF-8'], + fallback=True) + trans.install() directory = path + '/' + locale[0:2] + '/autogen' if not os.path.isdir(directory): weechat.prnt('', @@ -410,27 +415,27 @@ def docgen_cmd_cb(data, buffer, args): for plugin in commands: filename = directory + '/user/' + plugin + '_commands.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') + _file = open(tmpfilename, 'w') for command in sorted(commands[plugin]): _cmd = commands[plugin][command] args = translate(_cmd['args']) args_formats = args.split(' || ') desc = translate(_cmd['description']) args_desc = translate(_cmd['args_description']) - f.write('[[command_{0}_{1}]]\n'.format(plugin, command)) - f.write('[command]*`{0}`* {1}::\n\n'.format(command, desc)) - f.write('----\n') + _file.write('[[command_{0}_{1}]]\n'.format(plugin, command)) + _file.write('[command]*`{0}`* {1}::\n\n'.format(command, desc)) + _file.write('----\n') prefix = '/' + command + ' ' if args_formats != ['']: for fmt in args_formats: - f.write(prefix + fmt + '\n') + _file.write(prefix + fmt + '\n') prefix = ' ' * len(prefix) if args_desc: - f.write('\n') + _file.write('\n') for line in args_desc.split('\n'): - f.write(line + '\n') - f.write('----\n\n') - f.close() + _file.write(line + '\n') + _file.write('----\n\n') + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'commands') @@ -438,7 +443,7 @@ def docgen_cmd_cb(data, buffer, args): for config in options: filename = directory + '/user/' + config + '_options.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') + _file = open(tmpfilename, 'w') for section in sorted(options[config]): for option in sorted(options[config][section]): _opt = options[config][section][option] @@ -481,96 +486,98 @@ def docgen_cmd_cb(data, buffer, args): 'only, not background): \"*\" for bold, ' '\"!\" for reverse, \"/\" for italic, ' '\"_\" for underline') - f.write('* [[option_{0}.{1}.{2}]] *{3}.{4}.{5}*\n' - ''.format(config, section, option, config, section, - option)) - f.write('** {0}: `{1}`\n'.format(_('description'), desc)) - f.write('** {0}: {1}\n'.format(_('type'), type_nls)) - f.write('** {0}: {1} ({2}: `{3}`)\n' - ''.format(_('values'), values, _('default value'), - default_value)) + _file.write('* [[option_{0}.{1}.{2}]] *{3}.{4}.{5}*\n' + ''.format(config, section, option, config, + section, option)) + _file.write('** {0}: `{1}`\n'.format(_('description'), + desc)) + _file.write('** {0}: {1}\n'.format(_('type'), type_nls)) + _file.write('** {0}: {1} ({2}: `{3}`)\n' + ''.format(_('values'), values, + _('default value'), default_value)) if null_value_allowed: - f.write('** {0}\n' - ''.format(_('undefined value allowed (null)'))) - f.write('\n') - f.close() + _file.write('** {0}\n' + ''.format( + _('undefined value allowed (null)'))) + _file.write('\n') + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'options') # write infos hooked filename = directory + '/plugin_api/infos.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') - f.write('[width="100%",cols="^1,^2,6,6",options="header"]\n') - f.write('|===\n') - f.write('| {0} | {1} | {2} | {3}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'), - _('Arguments'))) + _file = open(tmpfilename, 'w') + _file.write('[width="100%",cols="^1,^2,6,6",options="header"]\n') + _file.write('|===\n') + _file.write('| {0} | {1} | {2} | {3}\n\n' + ''.format(_('Plugin'), _('Name'), _('Description'), + _('Arguments'))) for plugin in sorted(infos): for info in sorted(infos[plugin]): _inf = infos[plugin][info] desc = translate(_inf['description']) args_desc = translate(_inf['args_description'] or '-') - f.write('| {0} | {1} | {2} | {3}\n\n' - ''.format(escape(plugin), escape(info), - escape(desc), escape(args_desc))) - f.write('|===\n') - f.close() + _file.write('| {0} | {1} | {2} | {3}\n\n' + ''.format(escape(plugin), escape(info), + escape(desc), escape(args_desc))) + _file.write('|===\n') + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'infos') # write infos (hashtable) hooked filename = directory + '/plugin_api/infos_hashtable.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') - f.write('[width="100%",cols="^1,^2,6,6,6",options="header"]\n') - f.write('|===\n') - f.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'), - _('Hashtable (input)'), _('Hashtable (output)'))) + _file = open(tmpfilename, 'w') + _file.write('[width="100%",cols="^1,^2,6,6,6",options="header"]\n') + _file.write('|===\n') + _file.write('| {0} | {1} | {2} | {3} | {4}\n\n' + ''.format(_('Plugin'), _('Name'), _('Description'), + _('Hashtable (input)'), _('Hashtable (output)'))) for plugin in sorted(infos_hashtable): for info in sorted(infos_hashtable[plugin]): _inh = infos_hashtable[plugin][info] desc = translate(_inh['description']) args_desc = translate(_inh['args_description']) output_desc = translate(_inh['output_description']) or '-' - f.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(escape(plugin), escape(info), - escape(desc), escape(args_desc), - escape(output_desc))) - f.write('|===\n') - f.close() + _file.write('| {0} | {1} | {2} | {3} | {4}\n\n' + ''.format(escape(plugin), escape(info), + escape(desc), escape(args_desc), + escape(output_desc))) + _file.write('|===\n') + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'infos_hashtable') # write infolists hooked filename = directory + '/plugin_api/infolists.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') - f.write('[width="100%",cols="^1,^2,5,5,5",options="header"]\n') - f.write('|===\n') - f.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'), - _('Pointer'), _('Arguments'))) + _file = open(tmpfilename, 'w') + _file.write('[width="100%",cols="^1,^2,5,5,5",options="header"]\n') + _file.write('|===\n') + _file.write('| {0} | {1} | {2} | {3} | {4}\n\n' + ''.format(_('Plugin'), _('Name'), _('Description'), + _('Pointer'), _('Arguments'))) for plugin in sorted(infolists): for infolist in sorted(infolists[plugin]): _inl = infolists[plugin][infolist] desc = translate(_inl['description']) pointer_desc = translate(_inl['pointer_description']) or '-' args_desc = translate(_inl['args_description']) or '-' - f.write('| {0} | {1} | {2} | {3} | {4}\n\n' - ''.format(escape(plugin), escape(infolist), - escape(desc), escape(pointer_desc), - escape(args_desc))) - f.write('|===\n') - f.close() + _file.write('| {0} | {1} | {2} | {3} | {4}\n\n' + ''.format(escape(plugin), escape(infolist), + escape(desc), escape(pointer_desc), + escape(args_desc))) + _file.write('|===\n') + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'infolists') # write hdata hooked filename = directory + '/plugin_api/hdata.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') + _file = open(tmpfilename, 'w') for plugin in sorted(hdata): for hdata_name in sorted(hdata[plugin]): _hda = hdata[plugin][hdata_name] @@ -578,57 +585,62 @@ def docgen_cmd_cb(data, buffer, args): variables = _hda['vars'] variables_update = _hda['vars_update'] lists = _hda['lists'] - f.write('* \'{0}\': {1}\n'.format(escape(hdata_name), - escape(desc))) - f.write('** {0}: {1}\n'.format(_('plugin'), escape(plugin))) - f.write('** {0}:\n{1}'.format(_('variables'), - escape(variables))) + _file.write('* \'{0}\': {1}\n'.format(escape(hdata_name), + escape(desc))) + _file.write('** {0}: {1}\n'.format(_('plugin'), + escape(plugin))) + _file.write('** {0}:\n{1}'.format(_('variables'), + escape(variables))) if variables_update: - f.write('** {0}:\n{1}'.format(_('update allowed'), - escape(variables_update))) + _file.write('** {0}:\n{1}'.format( + _('update allowed'), + escape(variables_update))) if lists: - f.write('** {0}:\n{1}'.format(_('lists'), escape(lists))) - f.close() + _file.write('** {0}:\n{1}'.format(_('lists'), + escape(lists))) + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'hdata') # write completions hooked filename = directory + '/plugin_api/completions.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') - f.write('[width="65%",cols="^1,^2,8",options="header"]\n') - f.write('|===\n') - f.write('| {0} | {1} | {2}\n\n' - ''.format(_('Plugin'), _('Name'), _('Description'))) + _file = open(tmpfilename, 'w') + _file.write('[width="65%",cols="^1,^2,8",options="header"]\n') + _file.write('|===\n') + _file.write('| {0} | {1} | {2}\n\n' + ''.format(_('Plugin'), _('Name'), _('Description'))) for plugin in sorted(completions): for completion_item in sorted(completions[plugin]): _cmp = completions[plugin][completion_item] desc = translate(_cmp['description']) - f.write('| {0} | {1} | {2}\n\n' - ''.format(escape(plugin), escape(completion_item), - escape(desc))) - f.write('|===\n') - f.close() + _file.write('| {0} | {1} | {2}\n\n' + ''.format(escape(plugin), escape(completion_item), + escape(desc))) + _file.write('|===\n') + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'completions') # write url options filename = directory + '/plugin_api/url_options.txt' tmpfilename = filename + '.tmp' - f = open(tmpfilename, 'w') - f.write('[width="100%",cols="2,^1,7",options="header"]\n') - f.write('|===\n') - f.write('| {0} | {1} | {2}\n\n' - ''.format(_('Option'), _('Type'), _('Constants') + ' ^(1)^')) + _file = open(tmpfilename, 'w') + _file.write('[width="100%",cols="2,^1,7",options="header"]\n') + _file.write('|===\n') + _file.write('| {0} | {1} | {2}\n\n' + ''.format(_('Option'), _('Type'), + _('Constants') + ' ^(1)^')) for option in url_options: constants = option['constants'] if constants: constants = ' ' + constants - f.write('| {0} | {1} |{2}\n\n' - ''.format(escape(option['name']), escape(option['type']), - escape(constants))) - f.write('|===\n') - f.close() + _file.write('| {0} | {1} |{2}\n\n' + ''.format(escape(option['name']), + escape(option['type']), + escape(constants))) + _file.write('|===\n') + _file.close() update_file(filename, tmpfilename, num_files, num_files_updated, 'url_options') @@ -666,16 +678,15 @@ def docgen_cmd_cb(data, buffer, args): return weechat.WEECHAT_RC_OK -def docgen_completion_cb(data, completion_item, buffer, completion): +def docgen_completion_cb(data, completion_item, buf, completion): """Callback for completion.""" - global locale_list - for locale in locale_list: + for locale in LOCALE_LIST: weechat.hook_completion_list_add(completion, locale, 0, weechat.WEECHAT_LIST_POS_SORT) return weechat.WEECHAT_RC_OK -if __name__ == '__main__' and import_ok: +if __name__ == '__main__' and IMPORT_OK: if weechat.register(SCRIPT_NAME, SCRIPT_AUTHOR, SCRIPT_VERSION, SCRIPT_LICENSE, SCRIPT_DESC, '', ''): weechat.hook_command(SCRIPT_COMMAND,