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 breezy 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
36
commands as _mod_commands,
46
from .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'
69
s = '""\n"' + lineterm.join(map(_escape, lines)) + '"'
73
def _parse_source(source_text):
74
"""Get object to lineno mappings from given source_text"""
78
for node in ast.walk(ast.parse(source_text)):
79
# TODO: worry about duplicates?
80
if isinstance(node, ast.ClassDef):
81
# TODO: worry about nesting?
82
cls_to_lineno[node.name] = node.lineno
83
elif isinstance(node, ast.Str):
84
# Python AST gives location of string literal as the line the
85
# string terminates on. It's more useful to have the line the
86
# string begins on. Unfortunately, counting back newlines is
87
# only an approximation as the AST is ignorant of escaping.
88
str_to_lineno[node.s] = node.lineno - node.s.count('\n')
89
return cls_to_lineno, str_to_lineno
92
class _ModuleContext(object):
93
"""Record of the location within a source tree"""
95
def __init__(self, path, lineno=1, _source_info=None):
98
if _source_info is not None:
99
self._cls_to_lineno, self._str_to_lineno = _source_info
102
def from_module(cls, module):
103
"""Get new context from module object and parse source for linenos"""
104
sourcepath = inspect.getsourcefile(module)
105
# TODO: fix this to do the right thing rather than rely on cwd
106
relpath = os.path.relpath(sourcepath)
108
_source_info=_parse_source("".join(inspect.findsource(module)[0])))
110
def from_class(self, cls):
111
"""Get new context with same details but lineno of class in source"""
113
lineno = self._cls_to_lineno[cls.__name__]
114
except (AttributeError, KeyError):
115
mutter("Definition of %r not found in %r", cls, self.path)
117
return self.__class__(self.path, lineno,
118
(self._cls_to_lineno, self._str_to_lineno))
120
def from_string(self, string):
121
"""Get new context with same details but lineno of string in source"""
123
lineno = self._str_to_lineno[string]
124
except (AttributeError, KeyError):
125
mutter("String %r not found in %r", string[:20], self.path)
127
return self.__class__(self.path, lineno,
128
(self._cls_to_lineno, self._str_to_lineno))
131
class _PotExporter(object):
132
"""Write message details to output stream in .pot file format"""
134
def __init__(self, outf, include_duplicates=False):
136
if include_duplicates:
140
self._module_contexts = {}
142
def poentry(self, path, lineno, s, comment=None):
143
if self._msgids is not None:
144
if s in self._msgids:
150
comment = "# %s\n" % comment
151
mutter("Exporting msg %r at line %d in %r", s[:20], lineno, path)
153
"#: {path}:{lineno}\n"
158
path=path, lineno=lineno, comment=comment, msg=_normalize(s)))
160
def poentry_in_context(self, context, string, comment=None):
161
context = context.from_string(string)
162
self.poentry(context.path, context.lineno, string, comment)
164
def poentry_per_paragraph(self, path, lineno, msgid, include=None):
165
# TODO: How to split long help?
166
paragraphs = msgid.split('\n\n')
167
if include is not None:
168
paragraphs = filter(include, paragraphs)
170
self.poentry(path, lineno, p)
171
lineno += p.count('\n') + 2
173
def get_context(self, obj):
174
module = inspect.getmodule(obj)
176
context = self._module_contexts[module.__name__]
178
context = _ModuleContext.from_module(module)
179
self._module_contexts[module.__name__] = context
180
if inspect.isclass(obj):
181
context = context.from_class(obj)
185
def _write_option(exporter, context, opt, note):
186
if getattr(opt, 'hidden', False):
189
if getattr(opt, 'title', None):
190
exporter.poentry_in_context(context, opt.title,
191
"title of {name!r} {what}".format(name=optname, what=note))
192
for name, _, _, helptxt in opt.iter_switches():
194
if opt.is_hidden(name):
196
name = "=".join([optname, name])
198
exporter.poentry_in_context(context, helptxt,
199
"help of {name!r} {what}".format(name=name, what=note))
202
def _standard_options(exporter):
203
OPTIONS = option.Option.OPTIONS
204
context = exporter.get_context(option)
205
for name in sorted(OPTIONS):
207
_write_option(exporter, context.from_string(name), opt, "option")
210
def _command_options(exporter, context, cmd):
211
note = "option of {0!r} command".format(cmd.name())
212
for opt in cmd.takes_options:
213
# String values in Command option lists are for global options
214
if not isinstance(opt, str):
215
_write_option(exporter, context, opt, note)
218
def _write_command_help(exporter, cmd):
219
context = exporter.get_context(cmd.__class__)
221
dcontext = context.from_string(rawdoc)
222
doc = inspect.cleandoc(rawdoc)
224
def exclude_usage(p):
225
# ':Usage:' has special meaning in help topics.
226
# This is usage example of command and should not be translated.
227
if p.splitlines()[0] != ':Usage:':
230
exporter.poentry_per_paragraph(dcontext.path, dcontext.lineno, doc,
232
_command_options(exporter, context, cmd)
235
def _command_helps(exporter, plugin_name=None):
236
"""Extract docstrings from path.
238
This respects the Bazaar cmdtable/table convention and will
239
only extract docstrings from functions mentioned in these tables.
243
for cmd_name in _mod_commands.builtin_command_names():
244
command = _mod_commands.get_cmd_object(cmd_name, False)
247
if plugin_name is not None:
248
# only export builtins if we are not exporting plugin commands
250
note(gettext("Exporting messages from builtin command: %s"), cmd_name)
251
_write_command_help(exporter, command)
253
plugins = breezy.global_state.plugins
254
core_plugins = set(name for name in plugins
255
if plugins[name].path().startswith(breezy.__path__[0]))
257
for cmd_name in _mod_commands.plugin_command_names():
258
command = _mod_commands.get_cmd_object(cmd_name, False)
261
if plugin_name is not None and command.plugin_name() != plugin_name:
262
# if we are exporting plugin commands, skip plugins we have not specified.
264
if plugin_name is None and command.plugin_name() not in core_plugins:
265
# skip non-core plugins
266
# TODO: Support extracting from third party plugins.
268
note(gettext("Exporting messages from plugin command: {0} in {1}").format(
269
cmd_name, command.plugin_name() ))
270
_write_command_help(exporter, command)
273
def _error_messages(exporter):
274
"""Extract fmt string from breezy.errors."""
275
context = exporter.get_context(errors)
276
base_klass = errors.BzrError
277
for name in dir(errors):
278
klass = getattr(errors, name)
279
if not inspect.isclass(klass):
281
if not issubclass(klass, base_klass):
283
if klass is base_klass:
285
if klass.internal_error:
287
fmt = getattr(klass, "_fmt", None)
289
note(gettext("Exporting message from error: %s"), name)
290
exporter.poentry_in_context(context, fmt)
293
def _help_topics(exporter):
294
topic_registry = help_topics.topic_registry
295
for key in topic_registry.keys():
296
doc = topic_registry.get(key)
297
if isinstance(doc, str):
298
exporter.poentry_per_paragraph(
299
'dummy/help_topics/'+key+'/detail.txt',
301
elif callable(doc): # help topics from files
302
exporter.poentry_per_paragraph(
303
'en/help_topics/'+key+'.txt',
305
summary = topic_registry.get_summary(key)
306
if summary is not None:
307
exporter.poentry('dummy/help_topics/'+key+'/summary.txt',
311
def export_pot(outf, plugin=None, include_duplicates=False):
312
exporter = _PotExporter(outf, include_duplicates)
314
_standard_options(exporter)
315
_command_helps(exporter)
316
_error_messages(exporter)
317
_help_topics(exporter)
319
_command_helps(exporter, plugin)
added
removed
breezy/export_pot.py
