Package babel :: Package messages :: Module catalog :: Class Catalog

# Class Catalog

    object --+
             |
            Catalog

Representation of a message catalog.

Instance Methods

__init__(self, locale=None, domain=None, header_comment=`u'``# Translations template for PROJE``...`, project=None, version=None, copyright_holder=None, msgid_bugs_address=None, creation_date=None, revision_date=None, last_translator=None, language_team=None, charset=`'``utf-8``'`, fuzzy=True) Initialize the catalog object. |

__contains__(self, id) Return whether the catalog has a message with the specified ID. |

__len__(self) The number of messages in the catalog. |

`iterator`

__iter__(self) Iterates through all the entries in the catalog, in the order they were added, yielding a Message object for every entry. |

__repr__(self) repr(x) |

__delitem__(self, id) Delete the message with the specified ID. |

Message

__getitem__(self, id) Return the message with the specified ID. |

__setitem__(self, id, message) Add or update the message with the specified ID. |

add(self, id, string=None, locations=`(``)`, flags=`(``)`, auto_comments=`(``)`, user_comments=`(``)`, previous_id=`(``)`, lineno=None) Add or update the message with the specified ID. |

`iterator`

check(self) Run various validation checks on the translations in the catalog. |

update(self, template, no_fuzzy_matching=False) Update the catalog based on the given template catalog. |

Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__str__`

Instance Variables
| domain The message domain
| locale The locale or `None`
| project The project name
| version The project version
| last_translator Name and email address of the last translator.
| language_team Name and email address of the language team.
| creation_date Creation date of the template
| revision_date Last revision date of the catalog
| fuzzy Catalog header fuzzy bit (`True` or `False`)
| obsolete Dictionary of obsolete messages

Properties
`unicode` | header_comment The header comment for the catalog.
`list` | mime_headers The MIME headers of the catalog, used for the special `msgid ""` entry.
`int` | num_plurals The number of plurals used by the catalog or locale.
`basestring` | plural_expr The plural expression used by the catalog or locale.
`str` | plural_forms Return the plural forms declaration for the locale.
Inherited from `object`: `__class__`

Method Details

### __init__(self, locale=None, domain=None, header_comment=`u'``# Translations template for PROJE``...`, project=None, version=None, copyright_holder=None, msgid_bugs_address=None, creation_date=None, revision_date=None, last_translator=None, language_team=None, charset=`'``utf-8``'`, fuzzy=True)
(Constructor)

Initialize the catalog object.

Parameters:
  - `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
  - `header_comment` - the header comment as string, or `None` for the default header
  - `project` - the project's name
  - `version` - the project's version
  - `copyright_holder` - the copyright holder of the catalog
  - `msgid_bugs_address` - the email address or URL to submit bug reports to
  - `creation_date` - the date the catalog was created
  - `revision_date` - the date the catalog was revised
  - `last_translator` - the name and email of the last translator
  - `language_team` - the name and email of the language team
  - `charset` - the encoding to use in the output
  - `fuzzy` - the fuzzy bit on the catalog header
Overrides: object.__init__

### __len__(self)
(Length operator)

The number of messages in the catalog.

This does not include the special `msgid ""` entry.

### __repr__(self)
(Representation operator)

repr(x)

Overrides: object.__repr__
  (inherited documentation)

### __getitem__(self, id)
(Indexing operator)

Return the message with the specified ID.

Parameters:
  - `id` - the message ID
Returns: Message
  the message with the specified ID, or `None` if no such message is in the catalog

### __setitem__(self, id, message)
(Index assignment operator)

Add or update the message with the specified ID.

    >>> catalog = Catalog()
    >>> catalog[u'foo'] = Message(u'foo')
    >>> catalog[u'foo']
    <Message u'foo' (flags: [])>

If a message with that ID is already in the catalog, it is updated to include the locations and flags of the new message.

    >>> catalog = Catalog()
    >>> catalog[u'foo'] = Message(u'foo', locations=[('main.py', 1)])
    >>> catalog[u'foo'].locations
    [('main.py', 1)]
    >>> catalog[u'foo'] = Message(u'foo', locations=[('utils.py', 5)])
    >>> catalog[u'foo'].locations
    [('main.py', 1), ('utils.py', 5)]

Parameters:
  - `id` - the message ID
  - `message` - the Message object

### add(self, id, string=None, locations=`(``)`, flags=`(``)`, auto_comments=`(``)`, user_comments=`(``)`, previous_id=`(``)`, lineno=None)

Add or update the message with the specified ID.

    >>> catalog = Catalog()
    >>> catalog.add(u'foo')
    >>> catalog[u'foo']
    <Message u'foo' (flags: [])>

This method simply constructs a Message object with the given arguments and invokes __setitem__ with that object.

Parameters:
  - `id` - the message ID, or a `(singular, plural)` tuple for pluralizable messages
  - `string` - the translated message string, or a `(singular, plural)` tuple for pluralizable messages
  - `locations` - a sequence of `(filenname, lineno)` tuples
  - `flags` - a set or sequence of flags
  - `auto_comments` - a sequence of automatic comments
  - `user_comments` - a sequence of user comments
  - `previous_id` - the previous message ID, or a `(singular, plural)` tuple for pluralizable messages
  - `lineno` - the line number on which the msgid line was found in the PO file, if any

### check(self)

Run various validation checks on the translations in the catalog.

For every message which fails validation, this method yield a `(message, errors)` tuple, where `message` is the Message object and `errors` is a sequence of TranslationError objects.

Returns: `iterator`

### update(self, template, no_fuzzy_matching=False)

Update the catalog based on the given template catalog.

    >>> from babel.messages import Catalog
    >>> template = Catalog()
    >>> template.add('green', locations=[('main.py', 99)])
    >>> template.add('blue', locations=[('main.py', 100)])
    >>> template.add(('salad', 'salads'), locations=[('util.py', 42)])
    >>> catalog = Catalog(locale='de_DE')
    >>> catalog.add('blue', u'blau', locations=[('main.py', 98)])
    >>> catalog.add('head', u'Kopf', locations=[('util.py', 33)])
    >>> catalog.add(('salad', 'salads'), (u'Salat', u'Salate'),
    ...             locations=[('util.py', 38)])

    >>> catalog.update(template)
    >>> len(catalog)
    3

    >>> msg1 = catalog['green']
    >>> msg1.string
    >>> msg1.locations
    [('main.py', 99)]

    >>> msg2 = catalog['blue']
    >>> msg2.string
    u'blau'
    >>> msg2.locations
    [('main.py', 100)]

    >>> msg3 = catalog['salad']
    >>> msg3.string
    (u'Salat', u'Salate')
    >>> msg3.locations
    [('util.py', 42)]

Messages that are in the catalog but not in the template are removed from the main collection, but can still be accessed via the obsolete member:

    >>> 'head' in catalog
    False
    >>> catalog.obsolete.values()
    [<Message 'head' (flags: [])>]

Parameters:
  - `template` - the reference catalog, usually read from a POT file
  - `no_fuzzy_matching` - whether to use fuzzy matching of message IDs

Property Details

### header_comment

The header comment for the catalog.

    >>> catalog = Catalog(project='Foobar', version='1.0',
    ...                   copyright_holder='Foo Company')
    >>> print catalog.header_comment #doctest: +ELLIPSIS
    # Translations template for Foobar.
    # Copyright (C) ... Foo Company
    # This file is distributed under the same license as the Foobar project.
    # FIRST AUTHOR <EMAIL@ADDRESS>, ....
    #

The header can also be set from a string. Any known upper-case variables will be replaced when the header is retrieved again:

    >>> catalog = Catalog(project='Foobar', version='1.0',
    ...                   copyright_holder='Foo Company')
    >>> catalog.header_comment = '''\
    ... # The POT for my really cool PROJECT project.
    ... # Copyright (C) 1990-2003 ORGANIZATION
    ... # This file is distributed under the same license as the PROJECT
    ... # project.
    ... #'''
    >>> print catalog.header_comment
    # The POT for my really cool Foobar project.
    # Copyright (C) 1990-2003 Foo Company
    # This file is distributed under the same license as the Foobar
    # project.
    #

Get Method:
  _get_header_comment(self)
Set Method:
  _set_header_comment(self, string)
Type:
  `unicode`

### mime_headers

The MIME headers of the catalog, used for the special `msgid ""` entry.

The behavior of this property changes slightly depending on whether a locale is set or not, the latter indicating that the catalog is actually a template for actual translations.

Here's an example of the output for such a catalog template:

    >>> created = datetime(1990, 4, 1, 15, 30, tzinfo=UTC)
    >>> catalog = Catalog(project='Foobar', version='1.0',
    ...                   creation_date=created)
    >>> for name, value in catalog.mime_headers:
    ...     print '%s: %s' % (name, value)
    Project-Id-Version: Foobar 1.0
    Report-Msgid-Bugs-To: EMAIL@ADDRESS
    POT-Creation-Date: 1990-04-01 15:30+0000
    PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE
    Last-Translator: FULL NAME <EMAIL@ADDRESS>
    Language-Team: LANGUAGE <LL@li.org>
    MIME-Version: 1.0
    Content-Type: text/plain; charset=utf-8
    Content-Transfer-Encoding: 8bit
    Generated-By: Babel ...

And here's an example of the output when the locale is set:

    >>> revised = datetime(1990, 8, 3, 12, 0, tzinfo=UTC)
    >>> catalog = Catalog(locale='de_DE', project='Foobar', version='1.0',
    ...                   creation_date=created, revision_date=revised,
    ...                   last_translator='John Doe <jd@example.com>',
    ...                   language_team='de_DE <de@example.com>')
    >>> for name, value in catalog.mime_headers:
    ...     print '%s: %s' % (name, value)
    Project-Id-Version: Foobar 1.0
    Report-Msgid-Bugs-To: EMAIL@ADDRESS
    POT-Creation-Date: 1990-04-01 15:30+0000
    PO-Revision-Date: 1990-08-03 12:00+0000
    Last-Translator: John Doe <jd@example.com>
    Language-Team: de_DE <de@example.com>
    Plural-Forms: nplurals=2; plural=(n != 1)
    MIME-Version: 1.0
    Content-Type: text/plain; charset=utf-8
    Content-Transfer-Encoding: 8bit
    Generated-By: Babel ...

Get Method:
  _get_mime_headers(self)
Set Method:
  _set_mime_headers(self, headers)
Type:
  `list`

### num_plurals

The number of plurals used by the catalog or locale.

    >>> Catalog(locale='en').num_plurals
    2
    >>> Catalog(locale='ga').num_plurals
    3

Get Method:
  unreachable.num_plurals(self)
Type:
  `int`

### plural_expr

The plural expression used by the catalog or locale.

    >>> Catalog(locale='en').plural_expr
    '(n != 1)'
    >>> Catalog(locale='ga').plural_expr
    '(n==1 ? 0 : n==2 ? 1 : 2)'

Get Method:
  unreachable.plural_expr(self)
Type:
  `basestring`

### plural_forms

Return the plural forms declaration for the locale.

    >>> Catalog(locale='en').plural_forms
    'nplurals=2; plural=(n != 1)'
    >>> Catalog(locale='pt_BR').plural_forms
    'nplurals=2; plural=(n > 1)'

Get Method:
  unreachable.plural_forms(self)
Type:
  `str`