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__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

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`