Package pology :: Module catalog :: Class Catalog

Class Catalog

         object --+    
                  |    
monitored.Monitored --+
                      |
                     Catalog

Class for access and operations on PO catalogs.

Catalog behaves as an ordered sequence of messages. The typical way of iterating over the messages from a PO file on disk would be:

   cat = Catalog("relative/path/foo.po")
   for msg in cat:
       ...
       (do something with msg)
       ...
   cat.sync()

where sync() method is used to write any modifications back to the disk.

The header entry of the catalog is not part of the message sequence, but is provided by the header attribute, an object of type different from an ordinary message entry.

The catalog is a monitored class. Catalog message entries themeselves may also be monitored (default), but need not, depending on the mode of creation.

See Also:: Monitored, Message, MessageUnsafe, Header

Instance Methods

__init__(self, filename, create=False, truncate=False, wrapping=None, monitored=True, headonly=False, readfh=None)
Build a message catalog by reading from a PO file or creating anew.

__getattr__(self, att)
Attribute getter.

int

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

Message_base

__getitem__(self, ident)
Get message by position or another message.

Message_base

__setitem__(self, ident, msg)
Set message by position or another message.

bool

__contains__(self, msg)
Whether the message with the same key exists in the catalog.

bool

__eq__(self, ocat)
Whether two catalogs are equal in all apparent parts.

bool

__ne__(self, ocat)
Whether two catalogs are equal in all apparent parts.

int

find(self, msg, wobs=True)
Position of the message in the catalog.

Message_base or type(defmsg)

get(self, msg, defmsg=None)
Get message by key of another message, with default fallback.

int or None

add(self, msg, pos=None, srefsyn={})
Add a message to the catalog.

[int or None, ...]

add_more(self, msgpos, cumulative=False, srefsyn={})
Add more than one message to the catalog.

int

obspos(self)
Get canonical position of the first obsolete message.

add_last(self, msg)
Add a message to the selected end of catalog, if not already in it.

remove(self, ident)
Remove a message from the catalog, by position or another message.

remove_on_sync(self, ident)
Remove a message from the catalog, by position or another message, on the next sync.

bool

sync(self, force=False, noobsend=False, writefh=None)
Write catalog file to disk if any message has been modified.

sync_map(self)
Update message map.

int, float

insertion_inquiry(self, msg, srefsyn={})
Compute the tentative insertion of the message into the catalog.

bool

created(self)
Whether the catalog has been newly created (no existing PO file).

int

nplurals(self)
Number of msgstr fields expected for plural messages.

int

plural_index(self, number)
Msgstr field index in plural messages for given number.

[int*]

plural_indices_single(self)
Indices of the msgstr fields which are used for single number only.

[Message_base*]

select_by_key(self, msgctxt, msgid, wobs=False)
Select message from the catalog by the fields that define its key.

[Message_base*]

select_by_key_match(self, msgctxt, msgid, exctxt=False, exid=True, case=True, wobs=False)
Select messages from the catalog by matching key-defining fields.

[Message_base*]

select_by_msgid(self, msgid, wobs=False)
Select messages from the catalog by matching msgid field.

[Message_base*]

select_by_msgid_fuzzy(self, msgid, cutoff=0.6, wobs=False)
Select messages from the catalog by near-matching msgid field.

[Message_base*]

select_by_msgstr(self, msgstr0, wobs=False, lazy=False)
Select messages from the catalog inversely, by their msgstr[0].

string

encoding(self)
Report encoding used when syncing the catalog.

set_encoding(self, encoding)
Set encoding used when syncing the catalog.

set(string*) or None

accelerator(self)
Report characters used as accelerator markers in GUI messages.

set_accelerator(self, accels)
Set accelerator markers that can be expected in messages.

set(string*) or None

markup(self)
Report what types of markup can be expected in messages.

set_markup(self, mtypes)
Set markup types that can be expected in messages.

string or None

language(self)
Report language of the translation.

set_language(self, lang)
Set language of the translation.

[string*] or None

environment(self)
Report environments which the catalog is part of.

set_environment(self, envs)
Set environments which the catalog is part of.

(string...) or None

wrapping(self)
Report wrapping policy for message fields.

set_wrapping(self, wrapkw)
Set wrapping policy for message fields.

(string, string, string?)->[string]

wrapf(self)
Get wrapping function used for message fields.

[(string, [Message_base])]

messages_by_source(self)
Get messages grouped as lists by source.

sort_by_source(self)
Sort messages in catalog by source references.

update_header(self, project=None, title=None, copyright=None, license=None, name=None, email=None, teamemail=None, langname=None, langcode=None, encoding=None, ctenc=None, plforms=None, poeditor=None)
Update catalog header.

{string: [string*]*}

detect_renamed_sources(self, cat, minshare=0.7)
Heuristically determine possible renamings of source files from this catalog based on source files in the other catalog.

Inherited from monitored.Monitored: __setattr__, assert_spec_getattr, assert_spec_getitem, assert_spec_init, assert_spec_setattr, assert_spec_setitem, data

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __sizeof__, __str__, __subclasshook__

Instance Variables
string	filename the file name which the catalog was created with
Header	header the header entry
string	name (read-only) the name of the catalog

Properties
Inherited from `object`: `__class__`

Method Details

init(self, filename, create=False, truncate=False, wrapping=None, monitored=True, headonly=False, readfh=None)
(Constructor)

Build a message catalog by reading from a PO file or creating anew.

The message entries in the catalog may be monitored themselves or not. That is, when monitoring is requested, entries are represented by the Message class, otherwise with MessageUnsafe.

Monitored messages are usually appropriate when the application is expected to modify them. Non-monitored messages should provide better performance, so use them whenever the catalog is opened for read-only purposes (such as checks).

Catalog can also be opened in header-only mode, for better performance when only the header data is needed. This mode provides header attribute as usual, but the rest of entries are unavailable. If any of the operations dealing with message entries are invoked, an error is signaled.

Instead of opening and reading from catalog's filename, catalog can be read from a file-like object provided by readfh parameter. Same as when reading from file on disk, text will be decoded using catalog's encoding after reading it from readfh.

If a problem which prevents construction of a valid catalog is detected while parsing a PO file, CatalogSyntaxError is raised.

Parameters:

filename (string) - name of the PO catalog on disk, or new catalog
create (bool) - whether a blank catalog can be created when the PO file does not already exist, or signal an error
truncate (bool) - whether catalog should be empty (and with uninitialized header) regardless of whether it is opened or created
wrapping (sequence of strings) - sequence of keywords specifying wrapping policy for message text fields (msgid, msgstr, etc.). See select_field_wrapper function for possible keywords and their effects on wrapping. If given as None, it will be deduced from the catalog (see wrapping method).
monitored (bool) - whether the message entries are monitored
headonly (bool) - whether to open in header-only mode
readfh (file-like object) - file to read the catalog from

Overrides: object.__init__

getattr(self, att)
(Qualification operator)

Attribute getter.

Processes read-only attributes, and sends others to the base class.

Parameters:

att - name of the attribute to get

Returns:

attribute value

Overrides: monitored.Monitored.__getattr__

len(self)
(Length operator)

The number of messages in the catalog.

The number includes obsolete entries, and excludes header entry.

Returns: int: the number of messages

getitem(self, ident)
(Indexing operator)

Get message by position or another message.

If the position is out of range, or the lookup message does not have a counterpart in this catalog with the same key, an error is signaled.

Runtime complexity O(1), regardless of the ident type.

Parameters:

ident (int or Message_base) - position index or another message

Returns: Message_base

reference to the message in catalog

setitem(self, ident, msg)
(Index assignment operator)

Set message by position or another message.

If the position is out of range, or the lookup message does not have a counterpart in this catalog with the same key, an error is signaled.

Runtime complexity O(1), regardless of the ident type.

Parameters:

ident (int or Message_base) - position index or another message

Returns: Message_base

reference to the message in catalog

contains(self, msg)
(In operator)

Whether the message with the same key exists in the catalog.

Runtime complexity O(1).

Parameters:

msg (Message_base) - message to look for

Returns: bool

True if the message exists

eq(self, ocat)
(Equality operator)

Whether two catalogs are equal in all apparent parts.

Catalogs are considered equal if they are of the same length, their headers are equal, and each two messages with the same position are equal.

Runtime complexity O(n).

Returns: bool: True if catalogs are equal
Overrides: monitored.Monitored.__eq__

ne(self, ocat)

Whether two catalogs are equal in all apparent parts.

Equivalent to not (self == ocat).

Returns: bool: False if catalogs are equal
Overrides: monitored.Monitored.__ne__

find(self, msg, wobs=True)

Position of the message in the catalog.

Runtime complexity O(1).

Parameters:

msg (Message_base) - message to look for
wobs (bool) - obsolete messages considered non-existant if False

Returns: int

position index if the message exists, -1 otherwise

get(self, msg, defmsg=None)

Get message by key of another message, with default fallback.

If the lookup message msg does not have a counterpart in this catalog with the same key, defmsg is returned. msg can also be None, when defmsg is returned.

Runtime complexity O(1).

Parameters:

msg (Message_base or None) - message for the lookup by key
defmsg (any) - fallback in case lookup failed

Returns: Message_base or type(defmsg)

reference to the message in catalog, or default

add(self, msg, pos=None, srefsyn=`{}`)

Add a message to the catalog.

If the message with the same key already exists in the catalog, it will be replaced with the new message, ignoring position. The return value will be None.

If the message does not exist in the catalog, when the position is None, the insertion will be attempted such as that the messages be near according to the source references; if the position is not None, the message is inserted at the given position. The return value will be the true insertion position.

Negative position can be given as well. It counts backward from the first non-obsolete message if the message to be added is not obsolete, or from last message otherwise.

When the message is inserted according to source references, a dictionary of file paths to consider synonymous can be given by the srefsyn. The key is the file path for which the synonyms are being given, and the value the list of synonymous file paths. The mapping is not symmetric; if B is in the list of synonyms to A, A will not be automatically considered to be among synonyms of B, unless explicitly given in the list of synonyms to B.

Runtime complexity O(1) if the message is present in the catalog; O(n - pos) if the position is given and the message is not present; O(n) if the position is not given and the message is not present.

Parameters:

msg (Message_base) - message to insert
pos (int or None) - position index to insert at
srefsyn ({string: [string*]*}) - synonymous names to some of the source files

Returns: int or None

if inserted, the position where inserted

add_more(self, msgpos, cumulative=False, srefsyn=`{}`)

Add more than one message to the catalog.

Like add, except that several messages are added in one call. This significantly speeds up insertion when insertion positions of all messages are known beforehand.

Insertion positions can be given relative to state before the call, or cumulative to earlier insertions in the list. For example, if insertions are given as [(msg1, 2), (msg2, 5)] and not cumulative, then the resulting position for msg1 will be 2, and for msg2 6 (assuming that both messages actually got inserted). This behavior can be toggled by the cumulative parameter.

Parameters:

msgpos ([(Message_base, int), ...]) - messages with target insertion positions
cumulative (bool) - whether input positions are cumulative
srefsyn ({string: [string*]*}) - synonymous names to some of the source files

Returns: [int or None, ...]

positions where inserted, or None where replaced

obspos(self)

Get canonical position of the first obsolete message.

Canonical position of the first obsolete message is the position of first of the contiguous obsolete messages at the end of the catalog. Normally this should be the same as the position of the very first obsolete message, as all obsolete messages should be contiguously grouped at the end. But there is no enforcement of such grouping, therefore the more stricter definition.

If there are no messages in the catalog, or the last message is not obsolete, the position is reported as number of messages (i.e. one position after the last message).

Runtime complexity O(number of contiguous trailing obsolete messages).

Returns: int: canonical position of first obsolete message

add_last(self, msg)

Add a message to the selected end of catalog, if not already in it.

Synonym to cat.add(msg, cat.obspos()) if the message is not obsolete (i.e. tries to add the message after all non-obsolete), or to cat.add(msg, len(cat)) (tries to add at the very end). If the message already exits in the catalog (by key), same behavior as for add applies.

See Also: add

remove(self, ident)

Remove a message from the catalog, by position or another message.

If the position is out of range, or the lookup message does not have a counterpart in this catalog with the same key, an error is signaled.

Runtime complexity O(n), regardless of ident type. Use remove_on_sync() method for O(1) complexity, when the logic allows the removal to be delayed to syncing time.

Parameters:

ident (int or Message_base) - position index or another message

Returns:

None

remove_on_sync(self, ident)

Remove a message from the catalog, by position or another message, on the next sync.

If the position is out of range, or the lookup message does not have a counterpart in this catalog with the same key, an error is signaled.

Suited for for-in iterations over a catalog with a sync afterwards, so that the indices are not confused by removal, and good performance.

Runtime complexity O(1).

Parameters:

ident (int or Message_base) - position index or another message

Returns:

None

sync(self, force=False, noobsend=False, writefh=None)

Write catalog file to disk if any message has been modified.

All activities scheduled for sync-time are performed, such as delayed message removal.

If catalog is monitored, unmodified messages (and message parts) are not reformatted unless forced.

Instead of opening and writing into catalog's filename, catalog can be written to a file-like object provided by writefh parameter. Same as when writing to file on disk, text will be encoded using catalog's encoding before writing it to writefh.

Parameters:

force (bool) - whether to reformat unmodified messages
noobsend (bool) - do not reorder messages to group all obsolete at end
writefh (file-like object) - file to write the catalog to

Returns: bool

True if the file was modified, False otherwise

sync_map(self)

Update message map.

In case there were any modifications to message keys, or any pending removals issued, this function will update the sequence of messages such that membership operations work properly again. Obsolete messages will be moved to end of catalog. Referent line and entry numbers will remain invalid, as catalog will not be written out.

This is a less expensive alternative to syncing the catalog, when it is only necessary to continue using it in synced state, rather than actually writing it out.

insertion_inquiry(self, msg, srefsyn=`{}`)

Compute the tentative insertion of the message into the catalog.

The tentative insertion is a tuple of position of a message when it would be inserted into the catalog, and the weight indicating the quality of positioning. The weight is computed by analyzing the source references.

Runtime complexity O(n).

Parameters:

msg (Message_base) - message to compute the tentative insertion for
srefsyn ({string: [string*]*}) - synonymous names to some of the source files

Returns: int, float

the insertion position and its weight

created(self)

Whether the catalog has been newly created (no existing PO file).

A catalog is no longer considered newly created after the first sync.

Returns: bool: True if newly created, False otherwise

nplurals(self)

Number of msgstr fields expected for plural messages.

Determined by the Plural-Forms header field; if this field is absent from the header, defaults to 1.

Returns: int: number of plurals

plural_index(self, number)

Msgstr field index in plural messages for given number.

Determined by the Plural-Forms header field; if this field is absent from the header, defaults to 0.

Parameters:

number (int) - the number to determine the plural form for

Returns: int

index of msgstr field

plural_indices_single(self)

Indices of the msgstr fields which are used for single number only.

Returns: [int*]: msgstr indices used for single numbers

select_by_key(self, msgctxt, msgid, wobs=False)

Select message from the catalog by the fields that define its key.

If matched, the message is returned as a single-element list, or an empty list when there is no match. This is so that the result of this method is in line with other select_* methods.

Runtime complexity as that of find.

Parameters:

msgctxt (string or None) - the text of msgctxt field
msgid (string) - the text of msgid field
wobs (bool) - whether to include obsolete messages in selection

Returns: [Message_base*]

selected messages

select_by_key_match(self, msgctxt, msgid, exctxt=False, exid=True, case=True, wobs=False)

Select messages from the catalog by matching key-defining fields.

Parameters msgctxt and msgid are either exact values, to be matched by equality against message fields, or regular expression strings. Parameters exctxt and exid control which kind of match it is, respectively.

Runtime complexity O(n), unless all matches are exact, when as that of find.

Parameters:

msgctxt (string or None) - the text or regex string of msgctxt field
msgid (string) - the text or regex string of msgid field
exctxt (bool) - msgctxt is exact value if True, regex if False
exid (bool) - msgid is exact value if True, regex if False
case (bool) - whether regex matching is case-sensitive
wobs (bool) - whether to include obsolete messages in selection

Returns: [Message_base*]

selected messages

select_by_msgid(self, msgid, wobs=False)

Select messages from the catalog by matching msgid field.

Several messages may have the same msgid field, due to different msgctxt fields. Empty list is returned when there is no match.

Runtime complexity O(n).

Parameters:

msgid (string) - the text of msgid field
wobs (bool) - whether to include obsolete messages in selection

Returns: [Message_base*]

selected messages

select_by_msgid_fuzzy(self, msgid, cutoff=0.6, wobs=False)

Select messages from the catalog by near-matching msgid field.

The cutoff parameter determines the minimal admissible similarity (1.0 fo exact match).

The messages are returned ordered by decreasing similarity.

Runtime complexity O(n) * O(length(msgid)*avg(length(msgids))) (probably).

Parameters:

msgid (string) - the text of msgid field
cutoff (float) - minimal similarity
wobs (bool) - whether to include obsolete messages in selection

Returns: [Message_base*]

selected messages

select_by_msgstr(self, msgstr0, wobs=False, lazy=False)

Select messages from the catalog inversely, by their msgstr[0].

Several messages may have the same msgstr[0] field, so the return value is always a list of messages. Empty list is returned when there is no match.

Runtime complexity is O(n) if lazy is False. If lazy is True, complexity is O(n) for the first search, and then O(1) until next syncing of the catalog; if msgstr fields of some messages change in between, or messages are added or removed from the catalog, this is not seen until next syncing.

Parameters:

msgstr0 (string) - the text of msgstr[0] field
wobs (bool) - whether to include obsolete messages in selection
lazy (bool) - whether to assume msgstr are not modified between syncings

Returns: [Message_base*]

selected messages

encoding(self)

Report encoding used when syncing the catalog.

Encoding is determined from Content-Type header field.

It is not defined when the header will be examined, or if it will be reexamined when it changes. If you want to set encoding after the catalog has been opened, use set_encoding.

Returns: string: the encoding name

set_encoding(self, encoding)

Set encoding used when syncing the catalog.

Encoding set by this method will later be readable by the encoding method. This will also modify the catalog header Content-Type field.

Parameters:

encoding (string) - the encoding name

accelerator(self)

Report characters used as accelerator markers in GUI messages.

Accelerator characters are determined by looking for certain header fields, in this order: Accelerator-Marker, X-Accelerator-Marker. In each field, several accelerator markers can be stated as comma-separated list, or there may be several fields; the union of all parsed markers is reported.

If empty set is returned, it was determined that there are no accelerator markers in the catalog; if None, that there is no determination about markers.

It is not defined when the header will be examined, or if it will be reexamined when it changes. If you want to set accelerator markers after the catalog has been opened, use set_accelerator.

Returns: set(string*) or None: accelerator markers

set_accelerator(self, accels)

Set accelerator markers that can be expected in messages.

Accelerator markers set by this method will later be readable by the accelerator method. This will not modify the catalog header in any way; if that is desired, it must be done manually by manipulating the header fields.

If accels is given as None, it means the accelerator markers are undetermined; if empty, that there are no markers in messages.

Parameters:

accels (sequence of strings or None) - accelerator markers

markup(self)

Report what types of markup can be expected in messages.

Markup types are determined by looking for some header fields, which state markup types as short symbolic names, e.g. "html", "docbook", "mediawiki", etc. The header fields are tried in this order: Text-Markup, X-Text-Markup. In each field, several markup types can be stated as comma-separated list. If there are several fields, it is undefined from which one markup names are collected. Markup names are always reported in lower-case, regardless of the original casing used in the header. See set_markup for list of markup types currently observed by various Pology modules to influence processing behavior.

If empty set is returned, it was determined that there is no markup in the catalog; if None, that there is no determination about markup.

It is not defined when the header will be examined, or if it will be reexamined when it changes. If you want to set markup types after the catalog has been opened, use set_markup method.

Returns: set(string*) or None: markup names

set_markup(self, mtypes)

Set markup types that can be expected in messages.

Markup types set by this method will later be readable by the markup method. This will not modify the catalog header in any way; if that is desired, it must be done manually by manipulating the header fields.

If mtypes is given as None, it means the markup types are undetermined; if empty, that there is no markup in messages.

The following markup types are currently used by various parts of Pology to influence behavior on processing:

html: HTML 4.01
qtrich: Qt rich-text, (almost) a subset of HTML
kuit: UI semantic markup in KDE4
kde4: markup in KDE4 UI POs, a mix of Qt rich-text and KUIT
docbook4: Docbook 4.x markup, in documentation POs
xmlents: only XML-like entities, no other formal markup

Parameters:

mtypes (sequence of strings or None) - markup types

language(self)

Report language of the translation.

Language is determined by looking for the Language header field. If this field is present, it should contain the language code in line with GNU C library locales, e.g. pt for Portuguese, or pt_BR for Brazilian Portuguese. If the field is not present, language is considered undetermined, and None is returned.

It is not defined when the header will be examined, or if it will be reexamined when it changes (most probably not). If you want to set language after the catalog has been opened, use set_language method.

Returns: string or None: language code

set_language(self, lang)

Set language of the translation.

Language set by this method will later be readable by the language method. This will not modify the catalog header in any way; if that is desired, it must be done manually by manipulating the header fields.

If lang is given as None, it means the language is undetermined. If it is given as empty string, it means the language is deliberately considered unknown.

Parameters:

lang (string or None) - language code

environment(self)

Report environments which the catalog is part of.

Sometimes the language alone is not enough to determine all the non-technical aspects of translation. For example, in a given language but different translation domains, one translator may decide to use one of the two synonyms naming a concept, and the other translator the other synonym. Environments are a way to specify such sets of choices, so that automatic tools (e.g. terminology checker) can detect how to process a given catalog.

An environment can represent anything. It may be a single translator, who applies own set of choices to all the catalogs under own maintenance; it may be a translation project, with many cooperating translators; and so on. Each environment is named by an alphanumeric keyword (such as normalized project name, translator's name, etc.), and should be unique within a given language.

Environments are read from one of the following header fields: Environment, X-Environment. The value the field should be comma-separated list of environment keywords. If there are several environment fields, it is undefined from which the environments are read.

If more than one environment is stated, then wherever the conventions of two environments conflict, the environment mentioned later in the list should take precedence. For example, environment list such as "footp, jdoe" would mean to apply conventions of FOO translation project, ammended by that of translator Johnas Doemann.

It there is no environment header field, None is reported. Empty list is reported if such field exists, but its value is empty.

It is not defined when the header will be examined, or if it will be reexamined when it changes (most probably not). if you want to set environments after the catalog has been opened, use set_environment method.

Returns: [string*] or None: environment keywords

set_environment(self, envs)

Set environments which the catalog is part of.

Environments set by this method will later be readable by the environment method. This will not modify the catalog header in any way; if that is desired, it must be done manually by manipulating the header fields.

If envs is given as None, it means that the environments are undetermined; if empty, the catalog belongs to no environment.

Parameters:

envs (sequence of strings or None) - environment keywords

wrapping(self)

Report wrapping policy for message fields.

Long text fields in messages (msgid, msgstr, etc.) may be wrapped in different ways, as wrapping does not influence their semantics. (This is unlike translator and extracted comments, which are never wrapped, because division into lines may be significant.) PO processing tools will typically offer wrapping options, but it may be more convenient to have wrapping policy bound to the catalog, which tools respect unless overridden.

The following header fields are checked for wrapping policy, in given order: Wrapping, X-Wrapping. Wrapping policy (i.e. value of these header fields) is an unordered comma-separated list of wrapping keywords. See select_field_wrapper for possible keywords. If no wrapping policy field is found in the header, None is returned. If several wrapping policy fields are present, it is undefined which one is taken into account.

It is not defined when the header will be examined, or if it will be reexamined when it changes (most probably not). If you want to set wrapping after the catalog has been opened, use set_wrapping method.

Returns: (string...) or None: wrapping keywords

set_wrapping(self, wrapkw)

Set wrapping policy for message fields.

Wrapping policy set by this method will later be readable by the wrapping method. This will not modify the catalog header in any way; if that is desired, it must be done manually by manipulating the header fields.

Wrapping policy is a sequence of keywords. See select_field_wrapper for possible keywords. If None is given instead, it is passed directly to select_field_wrapper, which will construct default wrapper.

Parameters:

wrapkw ([string...] or None) - wrapping policy

wrapf(self)

Get wrapping function used for message fields.

Wrapping function is determined based on wrapping policy (see wrapping, set_wrapping). Wrapping function returned by this method is suitable as wrapf parameter in methods of Message objects.

Returns: (string, string, string?)->[string]: wrapping function

See Also: wrap_field

messages_by_source(self)

Get messages grouped as lists by source.

All messages sharing the same primary source file (their first source reference) are grouped and filed under that source file path. Grouping is represented by list of tuples of (source, list of messages), with both sources and messages within partial lists ordered by appearance.

Returns: [(string, [Message_base])]: messages grouped by sources

sort_by_source(self)

Sort messages in catalog by source references.

Source references within each message are sorted too, before messages are sorted by source references.

If any message changed its position due to sorting, sync_map is called at the end.

update_header(self, project=None, title=None, copyright=None, license=None, name=None, email=None, teamemail=None, langname=None, langcode=None, encoding=None, ctenc=None, plforms=None, poeditor=None)

Update catalog header.

If a piece of information is not given (i.e. None), the corresponding header field is left unmodified. If it is given as empty string, the corresponding header field is removed. PO revision date is updated always, to current date.

Some fields (as noted in parameter descriptions) are expanded on variables by applying the expand_vars function. For example:

   title="Translation of %project into %langname."

The following variables are available:

%basename: PO file base name
%poname: PO file base name without .po extension
%project: value of project parameter (if not None/empty)
%langname: value of langname parameter (if not None/empty)
%langcode: value of langcode parameter (if not None/empty)

Parameters:

project (string) - project name
title (string) - translation title (expanded on variables)
copyright (string) - copyright notice (expanded on variables)
license (string) - license notice (expanded on variables)
name (string) - translator's name
email (string) - translator's email address
teamemail (string) - language team's email address
langname (string) - full language name
langcode (string) - language code
encoding (string) - text encoding
ctenc (string) - content transfer encoding
plforms (string) - plural forms expression
poeditor (string) - translator's PO editor

Returns:

reference to header

detect_renamed_sources(self, cat, minshare=0.7)

Heuristically determine possible renamings of source files from this catalog based on source files in the other catalog.

To determine the possibility that the source file A from this catalog has been renamed into source file B in the other catalog cat, primarily the share of common messages to A and B is considered. The minimum needed commonality can be given by minshare parameter.

When a source file from this catalog is directly mentioned in the other catalog, it is immediatelly considered to have no possible renamings.

The return value is a dictionary in which the key is the source file and the value is the list of its possible renamed counterparts. The renaming list is never empty, i.e. if no renamings were detected for a given source file, that source file will not be present in the dictionary. The dictionary is fully symmetric: if source file B is in the renaming list of file A, then there will be an entry for file B with A in its renaming list (even when B is comming from the other catalog).

Instead of a single other catalog to test against, a sequence of several other catalogs can be given.

Parameters:

cat (Catalog or [Catalog*]) - catalog against which to test for renamings
minshare (float) - the minimum commonality between two source files to consider them as possible renaming pair (0.0-1.0)

Returns: {string: [string*]*}

the renaming dictionary

Instance Variable Details

name

(read-only) the name of the catalog

Determined as base of the filename, without extension.

Type:: string

Class Catalog

__init__(self, filename, create=False, truncate=False, wrapping=None, monitored=True, headonly=False, readfh=None) (Constructor)

__getattr__(self, att) (Qualification operator)

__len__(self) (Length operator)

__getitem__(self, ident) (Indexing operator)

__setitem__(self, ident, msg) (Index assignment operator)

__contains__(self, msg) (In operator)

__eq__(self, ocat) (Equality operator)

__ne__(self, ocat)

find(self, msg, wobs=True)

get(self, msg, defmsg=None)

add(self, msg, pos=None, srefsyn={})

add_more(self, msgpos, cumulative=False, srefsyn={})

obspos(self)

add_last(self, msg)

remove(self, ident)

remove_on_sync(self, ident)

sync(self, force=False, noobsend=False, writefh=None)

sync_map(self)

insertion_inquiry(self, msg, srefsyn={})

created(self)

nplurals(self)

plural_index(self, number)

plural_indices_single(self)

select_by_key(self, msgctxt, msgid, wobs=False)

select_by_key_match(self, msgctxt, msgid, exctxt=False, exid=True, case=True, wobs=False)

select_by_msgid(self, msgid, wobs=False)

select_by_msgid_fuzzy(self, msgid, cutoff=0.6, wobs=False)

select_by_msgstr(self, msgstr0, wobs=False, lazy=False)

encoding(self)

set_encoding(self, encoding)

accelerator(self)

set_accelerator(self, accels)

markup(self)

set_markup(self, mtypes)

language(self)

set_language(self, lang)

environment(self)

set_environment(self, envs)

wrapping(self)

set_wrapping(self, wrapkw)

wrapf(self)

messages_by_source(self)

sort_by_source(self)

update_header(self, project=None, title=None, copyright=None, license=None, name=None, email=None, teamemail=None, langname=None, langcode=None, encoding=None, ctenc=None, plforms=None, poeditor=None)

detect_renamed_sources(self, cat, minshare=0.7)

name

init(self, filename, create=False, truncate=False, wrapping=None, monitored=True, headonly=False, readfh=None)
(Constructor)

getattr(self, att)
(Qualification operator)

len(self)
(Length operator)

getitem(self, ident)
(Indexing operator)

setitem(self, ident, msg)
(Index assignment operator)

contains(self, msg)
(In operator)

eq(self, ocat)
(Equality operator)

ne(self, ocat)

add(self, msg, pos=None, srefsyn=`{}`)

add_more(self, msgpos, cumulative=False, srefsyn=`{}`)

insertion_inquiry(self, msg, srefsyn=`{}`)