← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/export_pot.py

  • Committer: Ian Clatworthy
  • Date: 2007-11-30 04:28:32 UTC
  • mto: (3054.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 3055.
  • Revision ID: ian.clatworthy@internode.on.net-20071130042832-6prruj0kzg3fodm8
chapter 2 tweaks

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/export_pot.py
1
 
# Copyright (C) 2011 Canonical Ltd
2
 
#
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.
7
 
#
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.
12
 
#
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
16
 
 
17
 
# The normalize function is taken from pygettext which is distributed
18
 
# with Python under the Python License, which is GPL compatible.
19
 
 
20
 
"""Extract docstrings from Bazaar commands.
21
 
 
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.
27
 
"""
28
 
 
29
 
from __future__ import absolute_import
30
 
 
31
 
import inspect
32
 
import os
33
 
 
34
 
from bzrlib import (
35
 
    commands as _mod_commands,
36
 
    errors,
37
 
    help_topics,
38
 
    option,
39
 
    plugin,
40
 
    help,
41
 
    )
42
 
from bzrlib.trace import (
43
 
    mutter,
44
 
    note,
45
 
    )
46
 
from bzrlib.i18n import gettext
47
 
 
48
 
 
49
 
def _escape(s):
50
 
    s = (s.replace('\\', '\\\\')
51
 
        .replace('\n', '\\n')
52
 
        .replace('\r', '\\r')
53
 
        .replace('\t', '\\t')
54
 
        .replace('"', '\\"')
55
 
        )
56
 
    return s
57
 
 
58
 
def _normalize(s):
59
 
    # This converts the various Python string types into a format that
60
 
    # is appropriate for .po files, namely much closer to C style.
61
 
    lines = s.split('\n')
62
 
    if len(lines) == 1:
63
 
        s = '"' + _escape(s) + '"'
64
 
    else:
65
 
        if not lines[-1]:
66
 
            del lines[-1]
67
 
            lines[-1] = lines[-1] + '\n'
68
 
        lines = map(_escape, lines)
69
 
        lineterm = '\\n"\n"'
70
 
        s = '""\n"' + lineterm.join(lines) + '"'
71
 
    return s
72
 
 
73
 
 
74
 
def _parse_source(source_text):
75
 
    """Get object to lineno mappings from given source_text"""
76
 
    import ast
77
 
    cls_to_lineno = {}
78
 
    str_to_lineno = {}
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
91
 
 
92
 
 
93
 
class _ModuleContext(object):
94
 
    """Record of the location within a source tree"""
95
 
 
96
 
    def __init__(self, path, lineno=1, _source_info=None):
97
 
        self.path = path
98
 
        self.lineno = lineno
99
 
        if _source_info is not None:
100
 
            self._cls_to_lineno, self._str_to_lineno = _source_info
101
 
 
102
 
    @classmethod
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)
108
 
        return cls(relpath,
109
 
            _source_info=_parse_source("".join(inspect.findsource(module)[0])))
110
 
 
111
 
    def from_class(self, cls):
112
 
        """Get new context with same details but lineno of class in source"""
113
 
        try:
114
 
            lineno = self._cls_to_lineno[cls.__name__]
115
 
        except (AttributeError, KeyError):
116
 
            mutter("Definition of %r not found in %r", cls, self.path)
117
 
            return self
118
 
        return self.__class__(self.path, lineno,
119
 
            (self._cls_to_lineno, self._str_to_lineno))
120
 
 
121
 
    def from_string(self, string):
122
 
        """Get new context with same details but lineno of string in source"""
123
 
        try:
124
 
            lineno = self._str_to_lineno[string]
125
 
        except (AttributeError, KeyError):
126
 
            mutter("String %r not found in %r", string[:20], self.path)
127
 
            return self
128
 
        return self.__class__(self.path, lineno,
129
 
            (self._cls_to_lineno, self._str_to_lineno))
130
 
 
131
 
 
132
 
class _PotExporter(object):
133
 
    """Write message details to output stream in .pot file format"""
134
 
 
135
 
    def __init__(self, outf, include_duplicates=False):
136
 
        self.outf = outf
137
 
        if include_duplicates:
138
 
            self._msgids = None
139
 
        else:
140
 
            self._msgids = set()
141
 
        self._module_contexts = {}
142
 
 
143
 
    def poentry(self, path, lineno, s, comment=None):
144
 
        if self._msgids is not None:
145
 
            if s in self._msgids:
146
 
                return
147
 
            self._msgids.add(s)
148
 
        if comment is None:
149
 
            comment = ''
150
 
        else:
151
 
            comment = "# %s\n" % comment
152
 
        mutter("Exporting msg %r at line %d in %r", s[:20], lineno, path)
153
 
        self.outf.write(
154
 
            "#: {path}:{lineno}\n"
155
 
            "{comment}"
156
 
            "msgid {msg}\n"
157
 
            "msgstr \"\"\n"
158
 
            "\n".format(
159
 
                path=path, lineno=lineno, comment=comment, msg=_normalize(s)))
160
 
 
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)
164
 
 
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)
170
 
        for p in paragraphs:
171
 
            self.poentry(path, lineno, p)
172
 
            lineno += p.count('\n') + 2
173
 
 
174
 
    def get_context(self, obj):
175
 
        module = inspect.getmodule(obj)
176
 
        try:
177
 
            context = self._module_contexts[module.__name__]
178
 
        except KeyError:
179
 
            context = _ModuleContext.from_module(module)
180
 
            self._module_contexts[module.__name__] = context
181
 
        if inspect.isclass(obj):
182
 
            context = context.from_class(obj)
183
 
        return context
184
 
 
185
 
 
186
 
def _write_option(exporter, context, opt, note):
187
 
    if getattr(opt, 'hidden', False):
188
 
        return   
189
 
    optname = opt.name
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():
194
 
        if name != optname:
195
 
            if opt.is_hidden(name):
196
 
                continue
197
 
            name = "=".join([optname, name])
198
 
        if helptxt:
199
 
            exporter.poentry_in_context(context, helptxt,
200
 
                "help of {name!r} {what}".format(name=name, what=note))
201
 
 
202
 
 
203
 
def _standard_options(exporter):
204
 
    OPTIONS = option.Option.OPTIONS
205
 
    context = exporter.get_context(option)
206
 
    for name in sorted(OPTIONS.keys()):
207
 
        opt = OPTIONS[name]
208
 
        _write_option(exporter, context.from_string(name), opt, "option")
209
 
 
210
 
 
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)
217
 
 
218
 
 
219
 
def _write_command_help(exporter, cmd):
220
 
    context = exporter.get_context(cmd.__class__)
221
 
    rawdoc = cmd.__doc__
222
 
    dcontext = context.from_string(rawdoc)
223
 
    doc = inspect.cleandoc(rawdoc)
224
 
 
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:':
229
 
            return True
230
 
 
231
 
    exporter.poentry_per_paragraph(dcontext.path, dcontext.lineno, doc,
232
 
        exclude_usage)
233
 
    _command_options(exporter, context, cmd)
234
 
 
235
 
 
236
 
def _command_helps(exporter, plugin_name=None):
237
 
    """Extract docstrings from path.
238
 
 
239
 
    This respects the Bazaar cmdtable/table convention and will
240
 
    only extract docstrings from functions mentioned in these tables.
241
 
    """
242
 
    from glob import glob
243
 
 
244
 
    # builtin commands
245
 
    for cmd_name in _mod_commands.builtin_command_names():
246
 
        command = _mod_commands.get_cmd_object(cmd_name, False)
247
 
        if command.hidden:
248
 
            continue
249
 
        if plugin_name is not None:
250
 
            # only export builtins if we are not exporting plugin commands
251
 
            continue
252
 
        note(gettext("Exporting messages from builtin command: %s"), cmd_name)
253
 
        _write_command_help(exporter, command)
254
 
 
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]
259
 
    # plugins
260
 
    for cmd_name in _mod_commands.plugin_command_names():
261
 
        command = _mod_commands.get_cmd_object(cmd_name, False)
262
 
        if command.hidden:
263
 
            continue
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.
266
 
            continue
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.
270
 
            continue
271
 
        note(gettext("Exporting messages from plugin command: {0} in {1}").format(
272
 
             cmd_name, command.plugin_name() ))
273
 
        _write_command_help(exporter, command)
274
 
 
275
 
 
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):
283
 
            continue
284
 
        if not issubclass(klass, base_klass):
285
 
            continue
286
 
        if klass is base_klass:
287
 
            continue
288
 
        if klass.internal_error:
289
 
            continue
290
 
        fmt = getattr(klass, "_fmt", None)
291
 
        if fmt:
292
 
            note(gettext("Exporting message from error: %s"), name)
293
 
            exporter.poentry_in_context(context, fmt)
294
 
 
295
 
 
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',
303
 
                    1, doc)
304
 
        elif callable(doc): # help topics from files
305
 
            exporter.poentry_per_paragraph(
306
 
                    'en/help_topics/'+key+'.txt',
307
 
                    1, doc(key))
308
 
        summary = topic_registry.get_summary(key)
309
 
        if summary is not None:
310
 
            exporter.poentry('dummy/help_topics/'+key+'/summary.txt',
311
 
                     1, summary)
312
 
 
313
 
 
314
 
def export_pot(outf, plugin=None, include_duplicates=False):
315
 
    exporter = _PotExporter(outf, include_duplicates)
316
 
    if plugin is None:
317
 
        _standard_options(exporter)
318
 
        _command_helps(exporter)
319
 
        _error_messages(exporter)
320
 
        _help_topics(exporter)
321
 
    else:
322
 
        _command_helps(exporter, plugin)