#!/usr/bin/env python

# -*- coding: utf-8 -*-

#

# License: MIT (see LICENSE file provided)

# vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4:

"""

**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, exporting only three

convenience functions (*pofile*, *mofile* and *detect_encoding*), and the

four core classes, *POFile*, *MOFile*, *POEntry* and *MOEntry* for creating

new files/entries.

**Basic example**:

>>> import polib

>>> # load an existing po file

>>> po = polib.pofile('tests/test_utf8.po')

>>> for entry in po:

...     # do something with entry...

...     pass

>>> # add an entry

>>> entry = polib.POEntry(msgid='Welcome', msgstr='Bienvenue')

>>> entry.occurrences = [('welcome.py', '12'), ('anotherfile.py', '34')]

>>> po.append(entry)

>>> # to save our modified po file:

>>> # po.save()

>>> # or you may want to compile the po file

>>> # po.save_as_mofile('tests/test_utf8.mo')

"""

__author__    = 'David JEAN LOUIS <izimobil@gmail.com>'

__version__   = '0.5.2'

__all__       = ['pofile', 'POFile', 'POEntry', 'mofile', 'MOFile', 'MOEntry',

                 'detect_encoding', 'escape', 'unescape', 'detect_encoding',]

import codecs

import struct

import textwrap

import types

default_encoding = 'utf-8'

# function pofile() {{{

def pofile(fpath, **kwargs):

    """

    Convenience function that parse the po/pot file *fpath* and return

    a POFile instance.

    **Keyword arguments**:

      - *fpath*: string, full or relative path to the po/pot file to parse

      - *wrapwidth*: integer, the wrap width, only useful when -w option was

        passed to xgettext (optional, default to 78)

      - *autodetect_encoding*: boolean, if set to False the function will

        not try to detect the po file encoding (optional, default to True)

      - *encoding*: string, an encoding, only relevant if autodetect_encoding

        is set to False

      - *check_for_duplicates*: whether to check for duplicate entries when

        adding entries to the file, default: False (optional)

    **Example**:

    >>> import polib

    >>> po = polib.pofile('tests/test_weird_occurrences.po',

    ...     check_for_duplicates=True)

    >>> po #doctest: +ELLIPSIS

    <POFile instance at ...>

    >>> import os, tempfile

    >>> all_attrs = ('msgctxt', 'msgid', 'msgstr', 'msgid_plural', 

    ...              'msgstr_plural', 'obsolete', 'comment', 'tcomment', 

    ...              'occurrences', 'flags', 'previous_msgctxt', 

    ...              'previous_msgid', 'previous_msgid_plural')

    >>> for fname in ['test_iso-8859-15.po', 'test_utf8.po']:

    ...     orig_po = polib.pofile('tests/'+fname)

    ...     tmpf = tempfile.NamedTemporaryFile().name

    ...     orig_po.save(tmpf)

    ...     try:

    ...         new_po = polib.pofile(tmpf)

    ...         for old, new in zip(orig_po, new_po):

    ...             for attr in all_attrs:

    ...                 if getattr(old, attr) != getattr(new, attr):

    ...                     getattr(old, attr)

    ...                     getattr(new, attr)

    ...     finally:

    ...         os.unlink(tmpf)

    >>> po_file = polib.pofile('tests/test_save_as_mofile.po')

    >>> tmpf = tempfile.NamedTemporaryFile().name

    >>> po_file.save_as_mofile(tmpf)

    >>> try:

    ...     mo_file = polib.mofile(tmpf)

    ...     for old, new in zip(po_file, mo_file):

    ...         if po_file._encode(old.msgid) != mo_file._encode(new.msgid):

    ...             'OLD: ', po_file._encode(old.msgid)

    ...             'NEW: ', mo_file._encode(new.msgid)

    ...         if po_file._encode(old.msgstr) != mo_file._encode(new.msgstr):

    ...             'OLD: ', po_file._encode(old.msgstr)

    ...             'NEW: ', mo_file._encode(new.msgstr)

    ...             print new.msgstr

    ... finally:

    ...     os.unlink(tmpf)

    """

    if kwargs.get('autodetect_encoding', True) == True:

        enc = detect_encoding(fpath)

    else:

        enc = kwargs.get('encoding', default_encoding)

    check_for_duplicates = kwargs.get('check_for_duplicates', False)

    parser = _POFileParser(

        fpath,

        encoding=enc,

        check_for_duplicates=kwargs.get('check_for_duplicates', False)

    )

    instance = parser.parse()

    instance.wrapwidth = kwargs.get('wrapwidth', 78)

    return instance

# }}}

# function mofile() {{{

def mofile(fpath, **kwargs):

    """

    Convenience function that parse the mo file *fpath* and return

    a MOFile instance.

    **Keyword arguments**:

      - *fpath*: string, full or relative path to the mo file to parse

      - *wrapwidth*: integer, the wrap width, only useful when -w option was

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

        the mo file (optional, default to 78)

      - *autodetect_encoding*: boolean, if set to False the function will

        not try to detect the po file encoding (optional, default to True)

      - *encoding*: string, an encoding, only relevant if autodetect_encoding

        is set to False

      - *check_for_duplicates*: whether to check for duplicate entries when

        adding entries to the file, default: False (optional)

    **Example**:

    >>> import polib

    >>> mo = polib.mofile('tests/test_utf8.mo', check_for_duplicates=True)

    >>> mo #doctest: +ELLIPSIS

    <MOFile instance at ...>

    >>> import os, tempfile

    >>> for fname in ['test_iso-8859-15.mo', 'test_utf8.mo']:

    ...     orig_mo = polib.mofile('tests/'+fname)

    ...     tmpf = tempfile.NamedTemporaryFile().name

    ...     orig_mo.save(tmpf)

    ...     try:

    ...         new_mo = polib.mofile(tmpf)

    ...         for old, new in zip(orig_mo, new_mo):

    ...             if old.msgid != new.msgid:

    ...                 old.msgstr

    ...                 new.msgstr

    ...     finally:

    ...         os.unlink(tmpf)

    """

    if kwargs.get('autodetect_encoding', True) == True:

        enc = detect_encoding(fpath, True)

    else:

        enc = kwargs.get('encoding', default_encoding)

    parser = _MOFileParser(

        fpath,

        encoding=enc,

        check_for_duplicates=kwargs.get('check_for_duplicates', False)

    )

    instance = parser.parse()

    instance.wrapwidth = kwargs.get('wrapwidth', 78)

    return instance

# }}}

# function detect_encoding() {{{

def detect_encoding(fpath, binary_mode=False):

    """

    Try to detect the encoding used by the file *fpath*. The function will

    return polib default *encoding* if it's unable to detect it.

    **Keyword argument**:

      - *fpath*: string, full or relative path to the mo file to parse.

    **Examples**:

    >>> print(detect_encoding('tests/test_noencoding.po'))

    utf-8

    >>> print(detect_encoding('tests/test_utf8.po'))

    UTF-8

    >>> print(detect_encoding('tests/test_utf8.mo', True))

    UTF-8

    >>> print(detect_encoding('tests/test_iso-8859-15.po'))

    ISO_8859-15

    >>> print(detect_encoding('tests/test_iso-8859-15.mo', True))

    ISO_8859-15

    """

    import re

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

    if binary_mode:

        mode = 'rb'

    else:

        mode = 'r'

    f = open(fpath, mode)

    for l in f.readlines():

        match = rx.search(l)

        if match:

            f.close()

            return match.group(1).strip()

    f.close()

    return default_encoding

# }}}

# function escape() {{{

def escape(st):

    """

    Escape special chars and return the given string *st*.

    **Examples**:

    >>> escape('\\t and \\n and \\r and " and \\\\')

    '\\\\t and \\\\n and \\\\r and \\\\" and \\\\\\\\'

    """

    return st.replace('\\', r'\\')\

             .replace('\t', r'\t')\

             .replace('\r', r'\r')\

             .replace('\n', r'\n')\

             .replace('\"', r'\"')

# }}}

# function unescape() {{{

def unescape(st):

    """

    Unescape special chars and return the given string *st*.

    **Examples**:

    >>> unescape('\\\\t and \\\\n and \\\\r and \\\\" and \\\\\\\\')

    '\\t and \\n and \\r and " and \\\\'

    >>> unescape(r'\\n')

    '\\n'

    >>> unescape(r'\\\\n')

    '\\\\n'

    """

    raw_strings = [

        (r'\\n', r'\n', '\n'),

        (r'\\r', r'\r', '\r'),

        (r'\\t', r'\t', '\t'),

    ]

    for a, b, c in raw_strings:

        if a in st:

            st = st.replace(a, b)

        else:

            st = st.replace(b, c)

    return st.replace(r'\"', '"').replace(r'\\', '\\')

# }}}

# class _BaseFile {{{

class _BaseFile(list):

    """

    Common parent class for POFile and MOFile classes.

    This class must **not** be instanciated directly.

    """

    def __init__(self, *args, **kwargs):

        """

        Constructor.

        **Keyword arguments**:

          - *fpath*: string, path to po or mo file

          - *wrapwidth*: integer, the wrap width, only useful when -w option

            was passed to xgettext to generate the po file that was used to

            format the mo file, default to 78 (optional),

          - *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, default: False (optional).

        """

        list.__init__(self)

        # the opened file handle

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

        # the width at which lines should be wrapped

        self.wrapwidth = kwargs.get('wrapwidth', 78)

        # the file encoding

        self.encoding = kwargs.get('encoding', default_encoding)

        # whether to check for duplicate entries or not

        self.check_for_duplicates = kwargs.get('check_for_duplicates', False)

        # header

        self.header = ''

        # both po and mo files have metadata

        self.metadata = {}

        self.metadata_is_fuzzy = 0

    def __str__(self):

        """

        String representation of the file.

        """

        ret = []

        entries = [self.metadata_as_entry()] + \

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

        for entry in entries:

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

        for entry in self.obsolete_entries():

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

        return '\n'.join(ret)

    def __contains__(self, entry):

        """

        Overriden 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 (case sensitive).

        **Keyword argument**:

          - *entry*: an instance of polib._BaseEntry

        **Tests**:

        >>> po = POFile()

        >>> e1 = POEntry(msgid='foobar', msgstr='spam')

        >>> e2 = POEntry(msgid='barfoo', msgstr='spam')

        >>> e3 = POEntry(msgid='foobar', msgstr='eggs')

        >>> e4 = POEntry(msgid='spameggs', msgstr='eggs')

        >>> po.append(e1)

        >>> po.append(e2)

        >>> e1 in po

        True

        >>> e2 not in po

        False

        >>> e3 in po

        True

        >>> e4 in po

        False

        """

        return self.find(entry.msgid, by='msgid') is not None

    def append(self, entry):

        """

        Overriden method to check for duplicates entries, if a user tries to

        add an entry that already exists, the method will raise a ValueError

        exception.

        **Keyword argument**:

          - *entry*: an instance of polib._BaseEntry

        **Tests**:

        >>> e1 = POEntry(msgid='foobar', msgstr='spam')

        >>> e2 = POEntry(msgid='foobar', msgstr='eggs')

        >>> po = POFile(check_for_duplicates=True)

        >>> po.append(e1)

        >>> try:

        ...     po.append(e2)

        ... except ValueError, e:

        ...     unicode(e)

        u'Entry "foobar" already exists'

        """

        if self.check_for_duplicates and entry in self:

            raise ValueError('Entry "%s" already exists' % entry.msgid)

        super(_BaseFile, self).append(entry)

    def insert(self, index, entry):

        """

        Overriden method to check for duplicates entries, if a user tries to

        insert an entry that already exists, the method will raise a ValueError

        exception.

        **Keyword arguments**:

          - *index*: index at which the entry should be inserted

          - *entry*: an instance of polib._BaseEntry

        **Tests**:

        >>> import polib

        >>> polib.check_for_duplicates = True

        >>> e1 = POEntry(msgid='foobar', msgstr='spam')

        >>> e2 = POEntry(msgid='barfoo', msgstr='eggs')

        >>> e3 = POEntry(msgid='foobar', msgstr='eggs')

        >>> po = POFile(check_for_duplicates=True)

        >>> po.insert(0, e1)

        >>> po.insert(1, e2)

        >>> try:

        ...     po.insert(0, e3)

        ... except ValueError, e:

        ...     unicode(e)

        u'Entry "foobar" already exists'

        """

        if self.check_for_duplicates and entry in self:

            raise ValueError('Entry "%s" already exists' % entry.msgid)

        super(_BaseFile, self).insert(index, entry)

    def __repr__(self):

        """Return the official string representation of the object."""

        return '<%s instance at %x>' % (self.__class__.__name__, id(self))

    def metadata_as_entry(self):

        """

        Return the metadata as an entry:

        >>> import polib

        >>> po = polib.pofile('tests/test_fuzzy_header.po')

        >>> unicode(po) == unicode(open('tests/test_fuzzy_header.po').read())

        True

        """

        e = POEntry(msgid='')

        mdata = self.ordered_metadata()

        if mdata:

            strs = []

            e._multiline_str['msgstr'] = ''

            for name, value in mdata:

                # Strip whitespace off each line in a multi-line entry

                strs.append('%s: %s' % (name, value))

            e.msgstr = '\n'.join(strs) + '\n'

            e._multiline_str['msgstr'] = '__POLIB__NL__'.join(

                    [s + '\n' for s in strs])

        if self.metadata_is_fuzzy:

            e.flags.append('fuzzy')

        return e

    def save(self, fpath=None, repr_method='__str__'):

        """

        Save the po file to file *fpath* if no file handle exists for

        the object. If there's already an open 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.

        """

        if self.fpath is None and fpath is None:

            raise IOError('You must provide a file path to save() method')

        contents = getattr(self, repr_method)()

        if fpath is None:

            fpath = self.fpath

        if repr_method == 'to_binary':

            fhandle = open(fpath, 'wb')

        else:

            fhandle = codecs.open(fpath, 'w', self.encoding)

            if type(contents) != types.UnicodeType:

                contents = contents.decode(self.encoding)

        fhandle.write(contents)

        fhandle.close()

    def find(self, st, by='msgid'):

        """

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

        attribute) matches the string *st*.