cmlenz@2: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@2: 
cmlenz@2: ================================
cmlenz@2: Distutils/Setuptools Integration
cmlenz@2: ================================
cmlenz@2: 
cmlenz@2: Babel provides commands for integration into ``setup.py`` scripts, based on
cmlenz@2: either the ``distutils`` package that is part of the Python standard library,
cmlenz@2: or the third-party ``setuptools`` package.
cmlenz@2: 
cmlenz@2: These commands are available by default when Babel has been properly installed,
cmlenz@2: and ``setup.py`` is using ``setuptools``. For projects that use plain old
cmlenz@40: ``distutils``, the commands need to be registered explicitly, for example:
cmlenz@40: 
cmlenz@40: .. code-block:: python
cmlenz@2: 
cmlenz@2:     from distutils.core import setup
cmlenz@54:     from babel.messages import frontend as babel
cmlenz@2:     
cmlenz@2:     setup(
cmlenz@2:         ...
cmlenz@2:         cmd_class = {'extract_messages': babel.extract_messages}
cmlenz@2:     )
cmlenz@2: 
cmlenz@2: 
cmlenz@2: .. contents:: Contents
cmlenz@2:    :depth: 2
cmlenz@2: .. sectnum::
cmlenz@2: 
cmlenz@2: 
cmlenz@2: extract_messages
cmlenz@2: ================
cmlenz@2: 
cmlenz@2: The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program:
cmlenz@2: it can extract localizable messages from a variety of difference source files,
cmlenz@2: and generate a PO (portable object) template file from the collected messages.
cmlenz@2: 
cmlenz@2: If the command has been correctly installed or registered, another project's
cmlenz@2: ``setup.py`` script should allow you to use the command::
cmlenz@2: 
cmlenz@2:     $ ./setup.py extract_messages --help
cmlenz@2:     Global options:
cmlenz@2:       --verbose (-v)  run verbosely (default)
cmlenz@2:       --quiet (-q)    run quietly (turns verbosity off)
cmlenz@2:       --dry-run (-n)  don't actually do anything
cmlenz@2:       --help (-h)     show detailed help message
cmlenz@77:     
cmlenz@2:     Options for 'extract_messages' command:
cmlenz@49:       --charset              charset to use in the output file
cmlenz@49:       --keywords (-k)        space-separated list of keywords to look for in
cmlenz@49:                              addition to the defaults
cmlenz@49:       --no-default-keywords  do not include the default keywords
cmlenz@49:       --mapping-file (-F)    path to the mapping configuration file
cmlenz@49:       --no-location          do not include location comments with filename and
cmlenz@49:                              line number
cmlenz@49:       --omit-header          do not include msgid "" entry in header
cmlenz@49:       --output-file (-o)     name of the output file
cmlenz@49:       --width (-w)           set output line width (default 76)
cmlenz@49:       --no-wrap              do not break long message lines, longer than the
cmlenz@49:                              output line width, into several lines
cmlenz@77:       --sort-output          generate sorted output (default False)
cmlenz@77:       --sort-by-file         sort output by file location (default False)
palgarvio@78:       --msgid-bugs-address   set report address for msgid
palgarvio@79:       --copyright-holder     set copyright holder in output
palgarvio@80:       --add-comments (-c)    place comment block with TAG (or those preceding
palgarvio@80:                              keyword lines) in output file. Seperate multiple TAGs
palgarvio@80:                              with commas(,)
cmlenz@62:       --input-dirs           directories that should be scanned for messages
cmlenz@77:     
cmlenz@77:     usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
cmlenz@77:        or: setup.py --help [cmd1 cmd2 ...]
cmlenz@77:        or: setup.py --help-commands
cmlenz@77:        or: setup.py cmd --help
cmlenz@2: 
palgarvio@51: Running the command will produce a PO template file::
cmlenz@2: 
cmlenz@49:     $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
cmlenz@2:     running extract_messages
cmlenz@49:     extracting messages from foobar/__init__.py
cmlenz@49:     extracting messages from foobar/core.py
cmlenz@49:     ...
palgarvio@51:     writing PO template file to foobar/locale/messages.pot
cmlenz@49: 
cmlenz@49: 
cmlenz@49: Method Mapping
cmlenz@49: --------------
cmlenz@49: 
cmlenz@49: The mapping of file patterns to extraction methods (and options) can be
cmlenz@49: specified using a configuration file that is pointed to using the
cmlenz@49: ``--mapping-file`` option shown above. Alternatively, you can configure the
cmlenz@49: mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
cmlenz@49: function:
cmlenz@49: 
cmlenz@49: .. code-block:: python
cmlenz@49: 
cmlenz@49:     setup(...
cmlenz@49:         
cmlenz@49:         message_extractors = {
cmlenz@62:             'foobar': [
cmlenz@62:                 ('**.py',                ('python', None),
cmlenz@62:                 ('**/templates/**.html', ('genshi', None),
cmlenz@62:                 ('**/templates/**.txt',  ('genshi', {
cmlenz@62:                     'template_class': 'genshi.template.text.TextTemplate'
cmlenz@62:                 })
cmlenz@62:             ],
cmlenz@49:         },
cmlenz@49:         
cmlenz@49:         ...
cmlenz@49:     )
cmlenz@2: 
cmlenz@2: 
cmlenz@2: Options
cmlenz@2: -------
cmlenz@2: 
cmlenz@2: As shown in the ``--help`` output above, the ``extract_messages`` command
cmlenz@2: accepts the following options:
cmlenz@2: 
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | Option                      | Description                                  |
cmlenz@49:   +=============================+==============================================+
cmlenz@49:   | ``--charset``               | charset to use in the output file            |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--keywords`` (``-k``)     | space-separated list of keywords to look for |
cmlenz@49:   |                             | in addition to the defaults                  |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--no-default-keywords``   | do not include the default keywords          |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--mapping-file`` (``-F``) | path to the mapping configuration file       |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--no-location``           | do not include location comments with        |
cmlenz@49:   |                             | filename and line number                     |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--omit-header``           | do not include msgid "" entry in header      |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--output-file`` (``-o``)  | name of the output file                      |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--width`` (``-w``)        | set output line width (default 76)           |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@49:   | ``--no-wrap``               | do not break long message lines, longer than |
cmlenz@49:   |                             | the output line width, into several lines    |
cmlenz@49:   +-----------------------------+----------------------------------------------+
cmlenz@62:   | ``--input-dirs``            | directories that should be scanned for       |
cmlenz@62:   |                             | messages                                     |
cmlenz@62:   +-----------------------------+----------------------------------------------+