Module polib
[hide private]
[frames] | no frames]

Module polib

source code

**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')

Version: 0.4.1

Author: David JEAN LOUIS <izimobil@gmail.com>

Classes [hide private]
  _BaseFile
Common parent class for POFile and MOFile classes.
  POFile
Po (or Pot) file reader/writer.
  MOFile
Mo file reader/writer.
  _BaseEntry
Base class for POEntry or MOEntry objects.
  POEntry
Represents a po file entry.
  MOEntry
Represents a mo file entry.
  _POFileParser
A finite state machine to parse efficiently and correctly po file format.
  _MOFileParser
A class to parse binary mo files.
Functions [hide private]
 
pofile(fpath, **kwargs)
Convenience function that parse the po/pot file *fpath* and return a POFile instance.
source code
 
mofile(fpath, **kwargs)
Convenience function that parse the mo file *fpath* and return a MOFile instance.
source code
 
detect_encoding(fpath)
Try to detect the encoding used by the file *fpath*.
source code
 
escape(st)
Escape special chars and return the given string *st*.
source code
 
unescape(st)
Unescape special chars and return the given string *st*.
source code
Variables [hide private]
  default_encoding = 'utf-8'
Function Details [hide private]

pofile(fpath, **kwargs)

source code 

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

**Example**:

>>> import polib
>>> po = polib.pofile('tests/test_weird_occurrences.po')
>>> po #doctest: +ELLIPSIS
<POFile instance at ...>
>>> import os, tempfile
>>> 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):
...             if old.msgid != new.msgid:
...                 old.msgid
...                 new.msgid
...             if old.msgstr != new.msgstr:
...                 old.msgid
...                 new.msgid
...     finally:
...         os.unlink(tmpf)

mofile(fpath, **kwargs)

source code 

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

**Example**:

>>> import polib
>>> mo = polib.mofile('tests/test_utf8.mo')
>>> 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)

detect_encoding(fpath)

source code 

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'))
UTF-8
>>> print(detect_encoding('tests/test_iso-8859-15.po'))
ISO_8859-15
>>> print(detect_encoding('tests/test_iso-8859-15.mo'))
ISO_8859-15

escape(st)

source code 

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 \\\\'

unescape(st)

source code 

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 \\'