.. -*- mode: rst; encoding: utf-8 -*-

================================
Distutils/Setuptools Integration
================================

Babel provides commands for integration into ``setup.py`` scripts, based on
either the ``distutils`` package that is part of the Python standard library,
or the third-party ``setuptools`` package.

These commands are available by default when Babel has been properly installed,
and ``setup.py`` is using ``setuptools``. For projects that use plain old
``distutils``, the commands need to be registered explicitly, for example:

.. code-block:: python

    from distutils.core import setup
    from babel.messages import frontend as babel
    
    setup(
        ...
        cmd_class = {'extract_messages': babel.extract_messages}
    )


.. contents:: Contents
   :depth: 2
.. sectnum::


extract_messages
================

The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program:
it can extract localizable messages from a variety of difference source files,
and generate a PO (portable object) template file from the collected messages.

If the command has been correctly installed or registered, another project's
``setup.py`` script should allow you to use the command::

    $ ./setup.py extract_messages --help
    Global options:
      --verbose (-v)  run verbosely (default)
      --quiet (-q)    run quietly (turns verbosity off)
      --dry-run (-n)  don't actually do anything
      --help (-h)     show detailed help message
    
    Options for 'extract_messages' command:
      --charset              charset to use in the output file
      --keywords (-k)        space-separated list of keywords to look for in
                             addition to the defaults
      --no-default-keywords  do not include the default keywords
      --mapping-file (-F)    path to the mapping configuration file
      --no-location          do not include location comments with filename and
                             line number
      --omit-header          do not include msgid "" entry in header
      --output-file (-o)     name of the output file
      --width (-w)           set output line width (default 76)
      --no-wrap              do not break long message lines, longer than the
                             output line width, into several lines
      --sort-output          generate sorted output (default False)
      --sort-by-file         sort output by file location (default False)
      --msgid-bugs-address   set report address for msgid
      --copyright-holder     set copyright holder in output
      --add-comments (-c)    place comment block with TAG (or those preceding
                             keyword lines) in output file. Seperate multiple TAGs
                             with commas(,)
      --input-dirs           directories that should be scanned for messages
    
    usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
       or: setup.py --help [cmd1 cmd2 ...]
       or: setup.py --help-commands
       or: setup.py cmd --help

Running the command will produce a PO template file::

    $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
    running extract_messages
    extracting messages from foobar/__init__.py
    extracting messages from foobar/core.py
    ...
    writing PO template file to foobar/locale/messages.pot


Method Mapping
--------------

The mapping of file patterns to extraction methods (and options) can be
specified using a configuration file that is pointed to using the
``--mapping-file`` option shown above. Alternatively, you can configure the
mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
function:

.. code-block:: python

    setup(...
        
        message_extractors = {
            'foobar': [
                ('**.py',                ('python', None),
                ('**/templates/**.html', ('genshi', None),
                ('**/templates/**.txt',  ('genshi', {
                    'template_class': 'genshi.template.text.TextTemplate'
                })
            ],
        },
        
        ...
    )


Options
-------

As shown in the ``--help`` output above, the ``extract_messages`` command
accepts the following options:

  +-----------------------------+----------------------------------------------+
  | Option                      | Description                                  |
  +=============================+==============================================+
  | ``--charset``               | charset to use in the output file            |
  +-----------------------------+----------------------------------------------+
  | ``--keywords`` (``-k``)     | space-separated list of keywords to look for |
  |                             | in addition to the defaults                  |
  +-----------------------------+----------------------------------------------+
  | ``--no-default-keywords``   | do not include the default keywords          |
  +-----------------------------+----------------------------------------------+
  | ``--mapping-file`` (``-F``) | path to the mapping configuration file       |
  +-----------------------------+----------------------------------------------+
  | ``--no-location``           | do not include location comments with        |
  |                             | filename and line number                     |
  +-----------------------------+----------------------------------------------+
  | ``--omit-header``           | do not include msgid "" entry in header      |
  +-----------------------------+----------------------------------------------+
  | ``--output-file`` (``-o``)  | name of the output file                      |
  +-----------------------------+----------------------------------------------+
  | ``--width`` (``-w``)        | set output line width (default 76)           |
  +-----------------------------+----------------------------------------------+
  | ``--no-wrap``               | do not break long message lines, longer than |
  |                             | the output line width, into several lines    |
  +-----------------------------+----------------------------------------------+
  | ``--input-dirs``            | directories that should be scanned for       |
  |                             | messages                                     |
  +-----------------------------+----------------------------------------------+