pology.catalog.Catalog

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