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
from __future__ import absolute_import
22
"""Extract docstrings from Bazaar commands.
24
This module only handles bzrlib objects that use strings not directly wrapped
25
by a gettext() call. To generate a complete translation template file, this
26
output needs to be combined with that of xgettext or a similar command for
27
extracting those strings, as is done in the bzr Makefile. Sorting the output
28
is also left to that stage of the process.
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
