1
# Copyright (C) 2011 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
# The normalize function is taken from pygettext which is distributed
18
# with Python under the Python License, which is GPL compatible.
20
"""Extract docstrings from Bazaar commands.
22
This module only handles bzrlib objects that use strings not directly wrapped
23
by a gettext() call. To generate a complete translation template file, this
24
output needs to be combined with that of xgettext or a similar command for
25
extracting those strings, as is done in the bzr Makefile. Sorting the output
26
is also left to that stage of the process.
29
from __future__ import absolute_import
35
commands as _mod_commands,
42
from bzrlib.trace import (
46
from bzrlib.i18n import gettext
50
s = (s.replace('\\', '\\\\')
59
# This converts the various Python string types into a format that
60
# is appropriate for .po files, namely much closer to C style.
63
s = '"' + _escape(s) + '"'
67
lines[-1] = lines[-1] + '\n'
68
lines = map(_escape, lines)
70
s = '""\n"' + lineterm.join(lines) + '"'
74
def _parse_source(source_text):
75
"""Get object to lineno mappings from given source_text"""
79
for node in ast.walk(ast.parse(source_text)):
80
# TODO: worry about duplicates?
81
if isinstance(node, ast.ClassDef):
82
# TODO: worry about nesting?
83
cls_to_lineno[node.name] = node.lineno
84
elif isinstance(node, ast.Str):
85
# Python AST gives location of string literal as the line the
86
# string terminates on. It's more useful to have the line the
87
# string begins on. Unfortunately, counting back newlines is
88
# only an approximation as the AST is ignorant of escaping.
89
str_to_lineno[node.s] = node.lineno - node.s.count('\n')
90
return cls_to_lineno, str_to_lineno
93
class _ModuleContext(object):
94
"""Record of the location within a source tree"""
96
def __init__(self, path, lineno=1, _source_info=None):
99
if _source_info is not None:
100
self._cls_to_lineno, self._str_to_lineno = _source_info
103
def from_module(cls, module):
104
"""Get new context from module object and parse source for linenos"""
105
sourcepath = inspect.getsourcefile(module)
106
# TODO: fix this to do the right thing rather than rely on cwd
107
relpath = os.path.relpath(sourcepath)
109
_source_info=_parse_source("".join(inspect.findsource(module)[0])))
111
def from_class(self, cls):
112
"""Get new context with same details but lineno of class in source"""
114
lineno = self._cls_to_lineno[cls.__name__]
115
except (AttributeError, KeyError):
116
mutter("Definition of %r not found in %r", cls, self.path)
118
return self.__class__(self.path, lineno,
119
(self._cls_to_lineno, self._str_to_lineno))
121
def from_string(self, string):
122
"""Get new context with same details but lineno of string in source"""
124
lineno = self._str_to_lineno[string]
125
except (AttributeError, KeyError):
126
mutter("String %r not found in %r", string[:20], self.path)
128
return self.__class__(self.path, lineno,
129
(self._cls_to_lineno, self._str_to_lineno))
132
class _PotExporter(object):
133
"""Write message details to output stream in .pot file format"""
135
def __init__(self, outf, include_duplicates=False):
137
if include_duplicates:
141
self._module_contexts = {}
143
def poentry(self, path, lineno, s, comment=None):
144
if self._msgids is not None:
145
if s in self._msgids:
151
comment = "# %s\n" % comment
152
mutter("Exporting msg %r at line %d in %r", s[:20], lineno, path)
154
"#: {path}:{lineno}\n"
159
path=path, lineno=lineno, comment=comment, msg=_normalize(s)))
161
def poentry_in_context(self, context, string, comment=None):
162
context = context.from_string(string)
163
self.poentry(context.path, context.lineno, string, comment)
165
def poentry_per_paragraph(self, path, lineno, msgid, include=None):
166
# TODO: How to split long help?
167
paragraphs = msgid.split('\n\n')
168
if include is not None:
169
paragraphs = filter(include, paragraphs)
171
self.poentry(path, lineno, p)
172
lineno += p.count('\n') + 2
174
def get_context(self, obj):
175
module = inspect.getmodule(obj)
177
context = self._module_contexts[module.__name__]
179
context = _ModuleContext.from_module(module)
180
self._module_contexts[module.__name__] = context
181
if inspect.isclass(obj):
182
context = context.from_class(obj)
186
def _write_option(exporter, context, opt, note):
187
if getattr(opt, 'hidden', False):
190
if getattr(opt, 'title', None):
191
exporter.poentry_in_context(context, opt.title,
192
"title of {name!r} {what}".format(name=optname, what=note))
193
for name, _, _, helptxt in opt.iter_switches():
195
if opt.is_hidden(name):
197
name = "=".join([optname, name])
199
exporter.poentry_in_context(context, helptxt,
200
"help of {name!r} {what}".format(name=name, what=note))
203
def _standard_options(exporter):
204
OPTIONS = option.Option.OPTIONS
205
context = exporter.get_context(option)
206
for name in sorted(OPTIONS.keys()):
208
_write_option(exporter, context.from_string(name), opt, "option")
211
def _command_options(exporter, context, cmd):
212
note = "option of {0!r} command".format(cmd.name())
213
for opt in cmd.takes_options:
214
# String values in Command option lists are for global options
215
if not isinstance(opt, str):
216
_write_option(exporter, context, opt, note)
219
def _write_command_help(exporter, cmd):
220
context = exporter.get_context(cmd.__class__)
222
dcontext = context.from_string(rawdoc)
223
doc = inspect.cleandoc(rawdoc)
225
def exclude_usage(p):
226
# ':Usage:' has special meaning in help topics.
227
# This is usage example of command and should not be translated.
228
if p.splitlines()[0] != ':Usage:':
231
exporter.poentry_per_paragraph(dcontext.path, dcontext.lineno, doc,
233
_command_options(exporter, context, cmd)
236
def _command_helps(exporter, plugin_name=None):
237
"""Extract docstrings from path.
239
This respects the Bazaar cmdtable/table convention and will
240
only extract docstrings from functions mentioned in these tables.
242
from glob import glob
245
for cmd_name in _mod_commands.builtin_command_names():
246
command = _mod_commands.get_cmd_object(cmd_name, False)
249
if plugin_name is not None:
250
# only export builtins if we are not exporting plugin commands
252
note(gettext("Exporting messages from builtin command: %s"), cmd_name)
253
_write_command_help(exporter, command)
255
plugin_path = plugin.get_core_plugin_path()
256
core_plugins = glob(plugin_path + '/*/__init__.py')
257
core_plugins = [os.path.basename(os.path.dirname(p))
258
for p in core_plugins]
260
for cmd_name in _mod_commands.plugin_command_names():
261
command = _mod_commands.get_cmd_object(cmd_name, False)
264
if plugin_name is not None and command.plugin_name() != plugin_name:
265
# if we are exporting plugin commands, skip plugins we have not specified.
267
if plugin_name is None and command.plugin_name() not in core_plugins:
268
# skip non-core plugins
269
# TODO: Support extracting from third party plugins.
271
note(gettext("Exporting messages from plugin command: {0} in {1}").format(
272
cmd_name, command.plugin_name() ))
273
_write_command_help(exporter, command)
276
def _error_messages(exporter):
277
"""Extract fmt string from bzrlib.errors."""
278
context = exporter.get_context(errors)
279
base_klass = errors.BzrError
280
for name in dir(errors):
281
klass = getattr(errors, name)
282
if not inspect.isclass(klass):
284
if not issubclass(klass, base_klass):
286
if klass is base_klass:
288
if klass.internal_error:
290
fmt = getattr(klass, "_fmt", None)
292
note(gettext("Exporting message from error: %s"), name)
293
exporter.poentry_in_context(context, fmt)
296
def _help_topics(exporter):
297
topic_registry = help_topics.topic_registry
298
for key in topic_registry.keys():
299
doc = topic_registry.get(key)
300
if isinstance(doc, str):
301
exporter.poentry_per_paragraph(
302
'dummy/help_topics/'+key+'/detail.txt',
304
elif callable(doc): # help topics from files
305
exporter.poentry_per_paragraph(
306
'en/help_topics/'+key+'.txt',
308
summary = topic_registry.get_summary(key)
309
if summary is not None:
310
exporter.poentry('dummy/help_topics/'+key+'/summary.txt',
314
def export_pot(outf, plugin=None, include_duplicates=False):
315
exporter = _PotExporter(outf, include_duplicates)
317
_standard_options(exporter)
318
_command_helps(exporter)
319
_error_messages(exporter)
320
_help_topics(exporter)
322
_command_helps(exporter, plugin)
added
removed
bzrlib/export_pot.py
