babel.messages.pofile Namespace Reference

Classes
class	_NormalizedString
class	PoFileError
class	PoFileParser

Functions
str	unescape (str string)
str	denormalize (str string)
list[str]	_extract_locations (str line)
Catalog	read_po (IO[AnyStr]|Iterable[AnyStr] fileobj, Locale|str|None locale=None, str|None domain=None, bool ignore_obsolete=False, str|None charset=None, bool abort_invalid=False)
str	escape (str string)
str	normalize (str string, str prefix='', int width=76)
str	_enclose_filename_if_necessary (str filename)
None	write_po (SupportsWrite[bytes] fileobj, Catalog catalog, int width=76, bool no_location=False, bool omit_header=False, bool sort_output=False, bool sort_by_file=False, bool ignore_obsolete=False, bool include_previous=False, bool include_lineno=True)
Iterable[str]	generate_po (Catalog catalog, *bool ignore_obsolete=False, bool include_lineno=True, bool include_previous=False, bool no_location=False, bool omit_header=False, Literal["message", "location"]|None sort_by=None, int width=76)
list[Message]	_sort_messages (Iterable[Message] messages, Literal["message", "location"]|None sort_by)

Variables
	WORD_SEP

Detailed Description

    babel.messages.pofile
    ~~~~~~~~~~~~~~~~~~~~~

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

    :copyright: (c) 2013-2025 by the Babel Team.
    :license: BSD, see LICENSE for more details.

Function Documentation

_enclose_filename_if_necessary()

str babel.messages.pofile._enclose_filename_if_necessary ( str  filename )

protected

Enclose filenames which include white spaces or tabs.

Do the same as gettext and enclose filenames which contain white
spaces or tabs with First Strong Isolate (U+2068) and Pop
Directional Isolate (U+2069).

_extract_locations()

list[str] babel.messages.pofile._extract_locations ( str  line )

protected

Extract locations from location comments.

Locations are extracted while properly handling First Strong
Isolate (U+2068) and Pop Directional Isolate (U+2069), used by
gettext to enclose filenames with spaces and tabs in their names.

_sort_messages()

list[Message] babel.messages.pofile._sort_messages ( Iterable[Message]  messages, Literal["message", "location"] | None  sort_by  )

protected

Sort the given message iterable by the given criteria.

Always returns a list.

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

denormalize()

str babel.messages.pofile.denormalize

(

str

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>

:param string: the string to denormalize

escape()

str babel.messages.pofile.escape

(

str

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

:param string: the string to escape

generate_po()

Iterable[str] babel.messages.pofile.generate_po	(	Catalog	catalog,
		*bool	ignore_obsolete = False,
		bool	include_lineno = True,
		bool	include_previous = False,
		bool	no_location = False,
		bool	omit_header = False,
		Literal["message", "location"] | None	sort_by = None,
		int	width = 76
	)

Yield text strings representing a ``gettext`` PO (portable object) file.

See `write_po()` for a more detailed description.

normalize()

str babel.messages.pofile.normalize	(	str	string,
		str	prefix = '',
		int	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"

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

read_po()

Catalog babel.messages.pofile.read_po	(	IO[AnyStr] | Iterable[AnyStr]	fileobj,
		Locale | str | None	locale = None,
		str | None	domain = None,
		bool	ignore_obsolete = False,
		str | None	charset = None,
		bool	abort_invalid = False
	)

Read messages from a ``gettext`` PO (portable object) file from the given
file-like object (or an iterable of lines) and return a `Catalog`.

>>> from datetime import datetime
>>> from io 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'])

.. versionadded:: 1.0
   Added support for explicit charset argument.

:param fileobj: the file-like object (or iterable of lines) to read the PO file from
:param 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)
:param domain: the message domain
:param ignore_obsolete: whether to ignore obsolete messages in the input
:param charset: the character set of the catalog.
:param abort_invalid: abort read if po file is invalid

unescape()

str babel.messages.pofile.unescape

(

str

string

)

Reverse `escape` the given string.

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

    :param string: the string to unescape

write_po()

None babel.messages.pofile.write_po	(	SupportsWrite[bytes]	fileobj,
		Catalog	catalog,
		int	width = 76,
		bool	no_location = False,
		bool	omit_header = False,
		bool	sort_output = False,
		bool	sort_by_file = False,
		bool	ignore_obsolete = False,
		bool	include_previous = False,
		bool	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 io 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>

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

Variable Documentation

WORD_SEP

babel.messages.pofile.WORD_SEP

Initial value:

=  re.compile('('
                      r'\s+|'                                 # any whitespace
                      r'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|'  # hyphenated words
                      r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w)'   # em-dash
                      ')')