Module ascript

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 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 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 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 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

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

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

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

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 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 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

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

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

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

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 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