pology.ascript

Package pology :: Module ascript |

# Module ascript

Process ascription configurations, catalogs, and histories.

Note: For the moment, this module is only for internal use within Pology. Interfaces may change arbitrarily between any two Pology releases.

Author: Chusslove Illich (Часлав Илић) <caslav.ilic@gmx.net>

License: GPLv3

Classes
| AscConfig Representation of an ascription configuration file.
| AscUser Representation of an ascription user.
| AscPoint Representation of an ascription point.

Functions
[(AscConfig, [(string, string)*])*] |
collect_ascription_associations(catpaths) Build up ascription associations for catalog paths. |
[AscPoint*] |
collect_ascription_history(msg, acat, aconf, nomrg=False, hfilter=None, shallow=False, addrem=None) Collect ascription history of a message. |
[AscPoint*] |
collect_ascription_history_segment(amsg, acat, aconf) Collect a segment of an ascription history. |
ascribe_modification(msg, user, dt, acat, aconf) Ascribe message modification. |
ascribe_review(msg, user, dt, tags, acat, aconf) Ascribe message review. |
bool |
ascription_equal(msg1, msg2) Whether two messages are equal from the ascription viewpoint. |
bool |
merge_modified(msg1, msg2) Whether second message may have been derived from first by merging with templates. |
int |
first_non_fuzzy(ahist, start=0) Find first non fuzzy message in the ascription history. |
bool |
has_tracked_parts(msg) Check whether the message has any parts which are tracked for ascription. |
set(string*) |
parse_users(userspec, aconf) Parse ascription user specification. |
set(string*) |
parse_review_tags(tagspec, aconf) Parse review tag specification. |
(Message_base, Catalog)->bool |
cached_matcher(expr) Fetch a cached message matcher for the given expression, for use in ascription selectors. |
set(string*) |
cached_users(userspec, aconf, utype=None) Fetch a cached set of users for the given user specification, for use in ascription selectors. |
set(string*) |
cached_review_tags(tagspec, aconf) Fetch a cached set of review tags for the given tag specification, for use in ascription selectors. |
(Message_base, Catalog, [AscPoint*], AscConfig)->bool (shallow), (...)->int/None (history) |
make_ascription_selector(selspecs, hist=False) Build compound ascription selector out of string specifications of basic selectors. |
import_ascription_extensions(modpath) Import extensions to ascription functionality from a Python module. |

Variables
| fld_sep = ``'``:``'``
| __package__ = ``'``pology``'``

Function Details

### collect_ascription_associations(catpaths) |
Build up ascription associations for catalog paths. For each catalog path, the ascription configuration to which it belongs is found and parsed, and the corresponding ascription catalog path assembled. The association is organized as list of two-tuples; the first element is the parsed ascription configuration, and the second element the list of two-tuples of original catalog paths and associated ascription catalog paths (whether the ascription catalog already exists or not). For example, if the input is:
       ["foo/alpha.po", "foo/bravo.po", "bar/november.po"]
and the files are covered by ascription configurations at `foo/ascription-config` and `bar/ascription-config`, the return value is:
       [(AscConfig("foo/ascription-config"),
        [("foo/alpha.po", "foo-ascript/alpha.po"),
         ("foo/bravo.po", "foo-ascript/bravo.po")]),
        (AscConfig("bar/ascription-config"),
         [("bar/november.po", "bar-ascript/november.po")])]
(assuming that both ascription configurations set `*-ascript/` directories as corresponding ascription catalog roots). Parameters: `catpaths` ([string*]) - a list of catalog paths Returns: [(AscConfig, [(string, string)*])*] the ascription association list

### collect_ascription_history(msg, acat, aconf, nomrg=False, hfilter=None, shallow=False, addrem=None) |
Collect ascription history of a message. The ascription history of `msg` is collected from the ascription catalog `acat`, falling under the ascription configuration `aconf`. The ascription history is a list of AscPoint objects, ordered from the newest to the oldest by date of ascription. Some ascription points may be due to merging with template, when the ascriptions on a catalog were made just after merging. In many cases of examining the history these ascriptions are not useful, so they can be removed by setting `nomrg` to `True`. Sometimes it may be convenient to operate on history in which the translations of historical messages have been filtered, and this filter can be specified with `hfilter`. If under filter two consecutive historical messages become equal, one of them will be eliminated from the history. History normally extends in the past through merging with templates (think of a paragraph-length message in which only one word was changed), so it may contain messages with keys different from the current message from some point and onwards. If only the history up to the earliest message with equal key is desired, `shallow` can be set to `True`. Sometimes it may be convenient to operate on incremental history, in which every historical message is actually a partial difference (added, removed or equal segments) from the previous historical message. This can be requested by setting `addrem` to one of the values as described in msg_diff function. Parameters: `msg` (Message_base) - the message from the original catalog `acat` (Catalog) - the ascription catalog corresponding to the original catalog `aconf` (AscConfig) - the ascription configuration which covers the catalogs `nomrg` (bool) - whether to eliminate from history pure merge ascriptions `hfilter` ((string)->string) - the filter to apply to `msgstr` fields of historical messages `shallow` (bool) - whether to collect history only up to last historical message with same key `addrem` (string) - make each historical message an incremental difference from the first earlier historical message; see same-name parameter of msg_diff for possible values Returns: [AscPoint*] the ascription history

### collect_ascription_history_segment(amsg, acat, aconf) |
Collect a segment of an ascription history. `amsg` is an ascription message from the ascription catalog `acat`, falling under the ascription configuration `aconf`, and it contains a part of the ascription history of some message. This function is used to get only that part of the ascription history. The ascription history segment is a list of AscPoint objects, ordered from the newest to the oldest by date of ascription. Parameters: `amsg` (Message_base) - the ascription message from the ascription catalog `acat` (Catalog) - the ascription catalog `aconf` (AscConfig) - the ascription configuration which covers the catalogs Returns: [AscPoint*] the ascription history segment

### ascribe_modification(msg, user, dt, acat, aconf) |
Ascribe message modification. Parameters: `msg` (Message_base) - modified message which is being ascribed `user` (string) - user to whom the ascription is made `dt` (datetime.datetime) - the time stamp when the ascription is made `acat` (Catalog) - the ascription catalogs `aconf` (AscConfig) - the ascription configuration

### ascribe_review(msg, user, dt, tags, acat, aconf) |
Ascribe message review. Parameters: `msg` (Message_base) - reviewed message which is being ascribed `user` (string) - user to whom the ascription is made `dt` (datetime.datetime) - the time stamp when the ascription is made `tags` ([string*]) - review tags `acat` (Catalog) - the ascription catalogs `aconf` (AscConfig) - the ascription configuration

### ascription_equal(msg1, msg2) |
Whether two messages are equal from the ascription viewpoint. Parameters: `msg1` (Message_base) - first message `msg2` (Message_base) - second message Returns: bool `True` if messages are equal, `False` otherwise

### merge_modified(msg1, msg2) |
Whether second message may have been derived from first by merging with templates. Parameters: `msg1` (Message_base) - first message `msg2` (Message_base) - second message Returns: bool `True` if `msg2` is derived by merging from `msg1`, `False` otherwise

### first_non_fuzzy(ahist, start=0) |
Find first non fuzzy message in the ascription history. Parameters: `ahist` ([AscPoint*]) - the ascription history `start` (int) - position in history to start searching from Returns: int index of first non-fuzzy message, or None if there is none such

### has_tracked_parts(msg) |
Check whether the message has any parts which are tracked for ascription. For example, a pristine untranslated message is considered to have no tracked parts. Returns: bool `True` if there are any tracked parts, `False` otherwise

### parse_users(userspec, aconf) |
Parse ascription user specification. The user specification is a comma-separated list of user names. If the list starts with tilde (~), all users defined in the ascription configuration but for those listed will be selected (inverted selection). If an undefined user (according to ascription configuration) is mentioned, an exception is raised. Parameters: `userspec` (string) - the user specification `aconf` (AscConfig) - the ascription configuration Returns: set(string*) selected user names

### parse_review_tags(tagspec, aconf) |
Parse review tag specification. The tag specification is a comma-separated list of tags. If the list starts with tilde (~), all review tags defined in the ascription configuration but for those listed will be selected (inverted selection). If an undefined tag (according to ascription configuration) is mentioned, an exception is raised. Parameters: `tagspec` (string) - the review tag specification `aconf` (AscConfig) - the ascription configuration Returns: set(string*) selected review tags

### cached_matcher(expr) |
Fetch a cached message matcher for the given expression, for use in ascription selectors. When this function is called for the first time on a new expression, the matcher function is created and cached. On subsequent invocations with the same expression, the matcher is fetched from the cache rather than created anew. Parameters: `expr` (string) - the matching expression; see make_msg_matcher for details Returns: (Message_base, Catalog)->bool the matcher function

### cached_users(userspec, aconf, utype=None) |
Fetch a cached set of users for the given user specification, for use in ascription selectors. When this function is called for the first time on a new combination of user specification `userspec`, ascription configuration `aconf`, and "user type" `utype`, the specification is parsed and users collected. On subsequent invocations with the same combination, the user set is fetched from the cache rather than created anew. `utype` is actually just an arbitrary string, for when you need to cache users by different categories. Parameters: `userspec` (string) - the user specification; see parse_users for details `aconf` (AscConfig) - the ascription configuration `utype` (string) - user type Returns: set(string*) the set of users

### cached_review_tags(tagspec, aconf) |
Fetch a cached set of review tags for the given tag specification, for use in ascription selectors. When this function is called for the first time on a new combination of tag specification `tagspec` and ascription configuration `aconf`, the specification is parsed and tags collected. On subsequent invocations with the same combination, the tag set is fetched from the cache rather than created anew. Parameters: `tagspec` (string) - the tag specification; see parse_review_tags for details `aconf` (AscConfig) - the ascription configuration Returns: set(string*) the set of tags

### make_ascription_selector(selspecs, hist=False) |
Build compound ascription selector out of string specifications of basic selectors. Selector specification string has the format NAME:ARG1:ARG2:... Instead of colon, separator can be any non-alphanumeric character used consistently, except for underscore and hyphen. The compound selector is obtained by constructing each basic selector according to the specification in turn, and linking them with AND-boolean semantics. Parameter `hist` determines whether the compound selector should be a shallow selector (`True`) or a history selector (`False`). If a history selector is required but cannot be made from the given composition of basic selectors, an exception is raised. Parameters: `selspecs` ([string*]) - specifications of basic selectors `hist` (bool) - `True` if the compound selector should be history selector, `False` if it should be shallow selector Returns: (Message_base, Catalog, [AscPoint*], AscConfig)->bool (shallow), (...)->int/None (history) the compound selector

### import_ascription_extensions(modpath) |
Import extensions to ascription functionality from a Python module. Additional selector factories can be introduced by defining the `asc_selector_factories` dictionary, in which the key is the selector name, and the value a tuple of the selector factory function and the indicator of whether the selector can be used as a history selector or not. For example:
       asc_selector_factories = {
           # key: (function, can_be_used_as_history_selector),
           "specsel1": (selector_specsel1, True),
           "specsel2": (selector_specsel2, False),
           ...
       }
Parameters: `modpath` (string) - path to Python file