**polib** allows you to manipulate, create, modify gettext files (pot, po and

mo files).  You can load existing files, iterate through it's entries, add,

modify entries, comments or metadata, etc. or create new po files from scratch.

**polib** provides a simple and pythonic API via the :func:`~polib.pofile` and

:func:`~polib.mofile` convenience functions.

__author__    = 'David Jean Louis <izimobil@gmail.com>'

__version__   = '0.6.4'

import array

import os

import re

import sys

# the default encoding to use when encoding cannot be detected

# _pofile_or_mofile {{{

def _pofile_or_mofile(f, type, **kwargs):

    """

    Internal function used by :func:`polib.pofile` and :func:`polib.mofile` to

    honor the DRY concept.

    # get the file encoding

    enc = kwargs.get('encoding')

    if enc is None:

        enc = detect_encoding(f, type == 'mofile')

    # parse the file

    kls = type == 'pofile' and _POFileParser or _MOFileParser

    parser = kls(

        f,

# function pofile() {{{

def pofile(pofile, **kwargs):

    """

    Convenience function that parses the po or pot file ``pofile`` and returns

    a :class:`~polib.POFile` instance.

    Arguments:

    ``pofile``

        string, full or relative path to the po/pot file or its content (data).

    ``wrapwidth``

        integer, the wrap width, only useful when the ``-w`` option was passed

        to xgettext (optional, default: ``78``).

    ``encoding``

        string, the encoding to use (e.g. "utf-8") (default: ``None``, the

        encoding will be auto-detected).

    ``check_for_duplicates``

        whether to check for duplicate entries when adding entries to the

        file (optional, default: ``False``).

    """

    return _pofile_or_mofile(pofile, 'pofile', **kwargs)

# }}}

def mofile(mofile, **kwargs):

    Convenience function that parses the mo file ``mofile`` and returns a

    :class:`~polib.MOFile` instance.

    Arguments:

    ``mofile``

        string, full or relative path to the mo file or its content (data).

    ``wrapwidth``

        integer, the wrap width, only useful when the ``-w`` option was passed

        to xgettext to generate the po file that was used to format the mo file

        (optional, default: ``78``).

    ``encoding``

        string, the encoding to use (e.g. "utf-8") (default: ``None``, the

        encoding will be auto-detected).

    ``check_for_duplicates``

        whether to check for duplicate entries when adding entries to the

        file (optional, default: ``False``).

    return _pofile_or_mofile(mofile, 'mofile', **kwargs)

def detect_encoding(file, binary_mode=False):

    Try to detect the encoding used by the ``file``. The ``file`` argument can

    be a PO or MO file path or a string containing the contents of the file.

    If the encoding cannot be detected, the function will return the value of

    ``default_encoding``.

    Arguments:

    ``file``

        string, full or relative path to the po/mo file or its content.

    ``binary_mode``

        boolean, set this to True if ``file`` is a mo file.

    """

    rx = re.compile(r'"?Content-Type:.+? charset=([\w_\-:\.]+)')

    def charset_exists(charset):

        """Check whether ``charset`` is valid or not."""

        try:

            codecs.lookup(charset)

        except LookupError:

            return False

        return True

    if not os.path.exists(file):

        match = rx.search(file)

        if match:

            enc = match.group(1).strip()

            if charset_exists(enc):

                return enc

        if binary_mode:

            mode = 'rb'

        else:

            mode = 'r'

        f = open(file, mode)

        for l in f.readlines():

            match = rx.search(l)

            if match:

                f.close()

                enc = match.group(1).strip()

                if charset_exists(enc):

                    return enc

        f.close()

    Escapes the characters ``\\\\``, ``\\t``, ``\\n``, ``\\r`` and ``"`` in

    the given string ``st`` and returns it.

    Unescapes the characters ``\\\\``, ``\\t``, ``\\n``, ``\\r`` and ``"`` in

    the given string ``st`` and returns it.

    Common base class for the :class:`~polib.POFile` and :class:`~polib.MOFile`

    classes. This class should **not** be instanciated directly.

        Constructor, accepts the following keyword arguments:

        ``pofile``

            string, the path to the po or mo file, or its content as a string.

        ``wrapwidth``

            integer, the wrap width, only useful when the ``-w`` option was

            passed to xgettext (optional, default: ``78``).

        ``encoding``

            string, the encoding to use, defaults to ``default_encoding``

            global variable (optional).

        ``check_for_duplicates``

            whether to check for duplicate entries when adding entries to the

            file, (optional, default: ``False``).

        pofile = kwargs.get('pofile', None)

        if pofile and os.path.exists(pofile):

            self.fpath = pofile

        else:

            self.fpath = kwargs.get('fpath')

    def __unicode__(self):

        Returns the unicode representation of the file.

            ret.append(entry.__unicode__(self.wrapwidth))

            ret.append(entry.__unicode__(self.wrapwidth))

        ret = '\n'.join(ret)

        if type(ret) != types.UnicodeType:

            return unicode(ret, self.encoding)

        return ret

    def __str__(self):

        """

        Returns the string representation of the file.

        """

        return unicode(self).encode(self.encoding)

        Overriden ``list`` method to implement the membership test (in and

        not in).

        The method considers that an entry is in the file if it finds an entry

        that has the same msgid (the test is **case sensitive**).

        Argument:

        ``entry``

            an instance of :class:`~polib._BaseEntry`.

    def __eq__(self, other):

        return unicode(self) == unicode(other)

        add an entry that is already in the file, the method will raise a

        ``ValueError`` exception.

        Argument:

        ``entry``

            an instance of :class:`~polib._BaseEntry`.

        add an entry that is already in the file, the method will raise a

        ``ValueError`` exception.

        Arguments:

        ``index``

            index at which the entry should be inserted.

        ``entry``

            an instance of :class:`~polib._BaseEntry`.

        Returns the file metadata as a :class:`~polib.POFile` instance.

        Saves the po file to ``fpath``.

        If it is an existing file and no ``fpath`` is provided, then the

        existing file is rewritten with the modified data.

        Keyword arguments:

        ``fpath``

            string, full or relative path to the file.

        ``repr_method``

            string, the method to use for output.

        # set the file path if not set

        if self.fpath is None and fpath:

            self.fpath = fpath

    def find(self, st, by='msgid', include_obsolete_entries=False,

             msgctxt=False):

        """

        Find the entry which msgid (or property identified by the ``by``

        argument) matches the string ``st``.

        Keyword arguments:

        ``st``

            string, the string to search for.

        ``by``

            string, the property to use for comparison (default: ``msgid``).

        ``include_obsolete_entries``

            boolean, whether to also search in entries that are obsolete.

        ``msgctxt``

            string, allows to specify a specific message context for the

            search.

        if include_obsolete_entries:

            entries = self[:]

        else:

            entries = [e for e in self if not e.obsolete]

        for e in entries:

                if msgctxt and e.msgctxt != msgctxt:

                    continue

        Convenience method that returns an ordered version of the metadata

        dictionnary. The return value is list of tuples (metadata name,

        metadata_value).