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

# no-check-code

#

# 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 via the :func:`~polib.pofile` and

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

"""

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

__version__   = '0.6.4'

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

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

import array

import codecs

import os

import re

import struct

import sys

import textwrap

import types

# the default encoding to use when encoding cannot be detected

default_encoding = 'utf-8'

# _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,

        encoding=enc,

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

    )

    instance = parser.parse()

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

    return instance

# }}}

# 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)

# }}}

# function mofile() {{{

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)

# }}}

# function detect_encoding() {{{

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

    else:

        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()

    return default_encoding

# }}}

# function escape() {{{

def escape(st):

    """

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

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

    """

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

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

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

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

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

# }}}

# function unescape() {{{

def unescape(st):

    """

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

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

    """

    def unescape_repl(m):

        m = m.group(1)

        if m == 'n':

            return '\n'

        if m == 't':

            return '\t'

        if m == 'r':

            return '\r'

        if m == '\\':

            return '\\'

        return m # handles escaped double quote

    return re.sub(r'\\(\\|n|t|r|")', unescape_repl, st)

# }}}

# class _BaseFile {{{

class _BaseFile(list):

    """

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

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

    """

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

        """

        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``).

        """

        list.__init__(self)

        # the opened file handle

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

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

            self.fpath = pofile

        else:

            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 __unicode__(self):

        """

        Returns the unicode 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.__unicode__(self.wrapwidth))

        for entry in self.obsolete_entries():

            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)

    def __contains__(self, entry):

        """

        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`.

        """

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

    def __eq__(self, other):

        return unicode(self) == unicode(other)

    def append(self, entry):

        """

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

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

        ``ValueError`` exception.

        Argument:

        ``entry``

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

        """

        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

        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`.

        """

        if self.check_for_duplicates and entry in self:

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

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

    def metadata_as_entry(self):

        """

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

        """

        e = POEntry(msgid='')

        mdata = self.ordered_metadata()

        if mdata:

            strs = []

            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'

        if self.metadata_is_fuzzy:

            e.flags.append('fuzzy')

        return e

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

        """

        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.

        """

        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()

        # 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 getattr(e, by) == st:

                if msgctxt and e.msgctxt != msgctxt:

                    continue

                return e

        return None

    def ordered_metadata(self):

        """

        Convenience method that returns an ordered version of the metadata

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

        metadata_value).

        """

        # copy the dict first

        metadata = self.metadata.copy()

        data_order = [

            'Project-Id-Version',

            'Report-Msgid-Bugs-To',

            'POT-Creation-Date',

            'PO-Revision-Date',

            'Last-Translator',

            'Language-Team',

            'MIME-Version',

            'Content-Type',

            'Content-Transfer-Encoding'

        ]

        ordered_data = []

        for data in data_order:

            try:

                value = metadata.pop(data)

                ordered_data.append((data, value))