babel.messages.pofile

module documentation

Reading and writing of files in the gettext PO (portable object) format.

Unknown Field: copyright
2013-2021 by the Babel Team.
Unknown Field: license
BSD, see LICENSE for more details.

Function	`read_po`	Read messages from a `gettext` PO (portable object) file from the given file-like object and return a `Catalog`.
Function	`write_po`	Write a `gettext` PO (portable object) template file for a given message catalog to the provided file-like object.
Constant	`WORD_SEP`	Undocumented
Class	`_NormalizedString`	Undocumented
Class	`PoFileError`	Exception thrown by PoParser when an invalid po file is encountered.
Class	`PoFileParser`	Support class to read messages from a `gettext` PO (portable object) file and add them to a `Catalog`
Function	`_sort_messages`	Sort the given message iterable by the given criteria.
Function	`denormalize`	Reverse the normalization done by the `normalize` function.
Function	`escape`	Escape the given string so that it can be included in double-quoted strings in `PO` files.
Function	`normalize`	Convert a string into a format that is appropriate for .po files.
Function	`unescape`	Reverse `escape` the given string.

def read_po(fileobj, locale=None, domain=None, ignore_obsolete=False, charset=None, abort_invalid=False):

Read messages from a gettext PO (portable object) file from the given file-like object and return a Catalog.

>>> from datetime import datetime
>>> from babel._compat import StringIO
>>> buf = StringIO('''
... #: main.py:1
... #, fuzzy, python-format
... msgid "foo %(name)s"
... msgstr "quux %(name)s"
...
... # A user comment
... #. An auto comment
... #: main.py:3
... msgid "bar"
... msgid_plural "baz"
... msgstr[0] "bar"
... msgstr[1] "baaz"
... ''')
>>> catalog = read_po(buf)
>>> catalog.revision_date = datetime(2007, 4, 1)

>>> for message in catalog:
...     if message.id:
...         print((message.id, message.string))
...         print(' ', (message.locations, sorted(list(message.flags))))
...         print(' ', (message.user_comments, message.auto_comments))
(u'foo %(name)s', u'quux %(name)s')
  ([(u'main.py', 1)], [u'fuzzy', u'python-format'])
  ([], [])
((u'bar', u'baz'), (u'bar', u'baaz'))
  ([(u'main.py', 3)], [])
  ([u'A user comment'], [u'An auto comment'])

New in version 1.0: Added support for explicit charset argument.

Parameters
fileobj	the file-like object to read the PO file from
locale	the locale identifier or `Locale` object, or `None` if the catalog is not bound to a locale (which basically means it's a template)
domain	the message domain
ignore_obsolete	whether to ignore obsolete messages in the input
charset	the character set of the catalog.
abort_invalid	abort read if po file is invalid

def write_po(fileobj, catalog, width=76, no_location=False, omit_header=False, sort_output=False, sort_by_file=False, ignore_obsolete=False, include_previous=False, include_lineno=True):

Write a gettext PO (portable object) template file for a given message catalog to the provided file-like object.

>>> catalog = Catalog()
>>> catalog.add(u'foo %(name)s', locations=[('main.py', 1)],
...             flags=('fuzzy',))
<Message...>
>>> catalog.add((u'bar', u'baz'), locations=[('main.py', 3)])
<Message...>
>>> from babel._compat import BytesIO
>>> buf = BytesIO()
>>> write_po(buf, catalog, omit_header=True)
>>> print(buf.getvalue().decode("utf8"))
#: main.py:1
#, fuzzy, python-format
msgid "foo %(name)s"
msgstr ""
<BLANKLINE>
#: main.py:3
msgid "bar"
msgid_plural "baz"
msgstr[0] ""
msgstr[1] ""
<BLANKLINE>
<BLANKLINE>

Parameters
fileobj	the file-like object to write to
catalog	the `Catalog` instance
width	the maximum line width for the generated output; use `None`, 0, or a negative number to completely disable line wrapping
no_location	do not emit a location comment for every message
omit_header	do not include the `msgid ""` entry at the top of the output
sort_output	whether to sort the messages in the output by msgid
sort_by_file	whether to sort the messages in the output by their locations
ignore_obsolete	whether to ignore obsolete messages and not include them in the output; by default they are included as comments
include_previous	include the old msgid as a comment when updating the catalog
include_lineno	include line number in the location comment

WORD_SEP =

Undocumented

Value

re.compile(r'(\s+|[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|(?<=[\w!"\'&\.,\?])-{2,}(?↵
=\w))')

def _sort_messages(messages, sort_by):

Sort the given message iterable by the given criteria.

Always returns a list.

Parameters
messages	An iterable of Messages.
sort_by	Sort by which criteria? Options are `message` and `location`.
Returns
list[Message]

def denormalize(string):

Reverse the normalization done by the normalize function.

>>> print(denormalize(r'''""
... "Say:\n"
... "  \"hello, world!\"\n"'''))
Say:
  "hello, world!"
<BLANKLINE>

>>> print(denormalize(r'''""
... "Say:\n"
... "  \"Lorem ipsum dolor sit "
... "amet, consectetur adipisicing"
... " elit, \"\n"'''))
Say:
  "Lorem ipsum dolor sit amet, consectetur adipisicing elit, "
<BLANKLINE>

Parameters
string	the string to denormalize

def escape(string):

Escape the given string so that it can be included in double-quoted strings in PO files.

>>> escape('''Say:
...   "hello, world!"
... ''')
'"Say:\\n  \\"hello, world!\\"\\n"'

Parameters
string	the string to escape

def normalize(string, prefix='', width=76):

Convert a string into a format that is appropriate for .po files.

>>> print(normalize('''Say:
...   "hello, world!"
... ''', width=None))
""
"Say:\n"
"  \"hello, world!\"\n"

>>> print(normalize('''Say:
...   "Lorem ipsum dolor sit amet, consectetur adipisicing elit, "
... ''', width=32))
""
"Say:\n"
"  \"Lorem ipsum dolor sit "
"amet, consectetur adipisicing"
" elit, \"\n"

Parameters
string	the string to normalize
prefix	a string that should be prepended to every line
width	the maximum line width; use `None`, 0, or a negative number to completely disable line wrapping

def unescape(string):

Reverse escape the given string.

>>> print(unescape('"Say:\\n  \\"hello, world!\\"\\n"'))
Say:
  "hello, world!"
<BLANKLINE>

Parameters
string	the string to unescape