h10n.core

A Core module contains objects which is used by h10n internally. End users don’t need to use this module directly.

class h10n.core.Locale(*args, **kwargs)

A Locale object is used to store translation catalogs. The locale accepts three arguments: name, translator and catalogs.

The name argument should be a locale name in format xx-YY, where xx is language code and YY is country code. Name itself, language and country codes can be accessed via name, lang and country attributes of the Locale object.

The translator argument should be an instance of h10n.translator.Translator class, which own current locale. Locale itself doesn’t use translator, but it can be useful in the filters of Message objects.

The catalogs argument should be a dictionary object, which store catalog names in keys and arguments for Catalog class in values.

Messages can be accessed using subscription interface. It can be accessed directly using key in format {catalog}:{message} or via catalog:

>>> l = Locale('en-US', None, {'test': {'message': u'Message'}})
>>> l['test']
<Catalog: test>
>>> l['test:message']
<Message: message>
>>> l['test:message'] is l['test']['message']
True
class h10n.core.Catalog(*args, **kwargs)

A Catalog object is used to extract Message objects from sources, group it in the Locale and provide HelperNamespace object for message’s filters. The Catalog accepts three arguments: name, locale and config.

The name argument is catalog name, as it defined in Locale. Is used for debugging only.

The locale argument should be an instance of Locale class, which own this catalog. Is used to create helper namespace and messages.

The config arguments should be a dictionary. If the dictionary contain callable object under the key factory, this object becomes factory of message source and all other values of the dictionary are passed as keyword arguments to this factory. Otherwise, config itself becomes message source.

The message source should be a dictionary-like object, which provides two methods __getitem__ and __setitem__. First one should return message definition or instance of Message class. Second one should accept instance of Message to store it in cache. See h10n.source doc-string to learn more about message sources.

The message definition should be a string or dictionary. If it passed as string, it is converted to dictionary {'msg': 'passed string'}. Dictionary should contain keyword arguments to Message constructor.

When message is requested, using subscription interface, catalog redirects request to the message source. If source return instance of Message, this instance is returned as is. If source return message definition, catalog extracts message prototype from locale, creates Message object, put it into source and return it as result.

Example:

>>> source_1 = {'prototype': 'test 1'}
>>> source_2 = {'test': {'prototype': 'source_1:prototype'}}
>>> locale = Locale('en-US', None, {'source_1': source_1,
...                                 'source_2': source_2})
>>> locale['source_2:test']
<Message: test>
>>> source_1
{'prototype': <Message: prototype>}
>>> source_2
{'test': <Message: test>}
class h10n.core.Message(*args, **kwargs)

A Message object store translation strings, associated metadata and formatting filter.

The Message accepts a number of keyword arguments: name, locale, prototype, key, msg, defaults, filter and helper.

The name argument is a name of the message, as it specified in Catalog. Is used for debugging only.

The locale argument should be an instance of Locale class. Is used in filter only and can be accessed via locale attribute.

The prototype argument should be an instance of this class. If it is passed as non-None value, current instance will inherit from prototype metadata and formatting filter.

The key argument is a template for key, which is used to choose appropriate translation string from msg, when it passed as dictionary.

The msg argument is a translation string itself. If is passed as dictionary object, the key argument is required.

The defaults argument should be a dictionary with default parameters, which will be used in the format() method.

The filter argument is a string of code, which is compiled into filter function. The code is a regular Python code with a pinch of syntax sugar. There are the rules of how the filter argument become a function:

  1. The code is prepended by def filter(self, kw):.
  2. Dollar-prefixed names is transformed to keys of kw, i.e. $name -> kw["name"].
  3. __prototype__ string is transformed to call of prototype’s filter, i.e. self.prototype.filter(self, kw).
  4. The result code is executed with the helper argument in the local namespace.

The helper is a HelperNamespace object, which will be available in the filter as global name.

Example:

>>> locale = Locale('en-US', None, {})
>>> helper = {'pluralize': 'h10n.helper.pluralize:Pluralize'}
>>> helper = HelperNamespace(locale, helper)
>>> prototype = Message(key='{form}',
...                     defaults={'count': 1},
...                     filter='$form = helper.pluralize($count)',
...                     helper=helper)
>>> message = Message(msg={'0': u'{count} item',
...                        '1': u'{count} items'},
...                   prototype=prototype)
>>> message.format()
u'1 item'
>>> message.format(count=3)
u'3 items'
format(*args, **kwargs)

Format translation string according to passed parameters.

Formatting is performed in following steps:

  1. Merge passed parameters with default ones.
  2. Pass parameters to filter.
  3. Format key, if it is not None.
  4. Choose translation string from msg, if msg is dictionary, or use msg as translation string.
  5. Format translation string and return result.

Formatting key and msg (translation string) is performed using standard format method of str and unicode objects. See PEP 3101 for details.

class h10n.core.HelperNamespace(locale, helpers)

A Helper Namespace object is used to store helpers in the Locale (actually are created by h10n.translator.Translator and named “application-level helpers”) and Catalog objects.

The Helper Namespace accepts two arguments: locale and helpers.

The locale argument should be an instance of Locale class.

The helpers argument should be a dictionary, which store helper aliases in its keys and helper specifications in its values. The alias become helper name in the namespace. The specification should be a Python path to the helper factory, similar to path using in the entry points from pkg_resources, i.e. python.path.to.helper.module:HelperFactory.

Each helper and locale pair is registered in the internal class-level registry. This mean, that two different Helper Namespace objects with similar locale and helper specification use shared helper object, instead of create diffrent objects for each instance of the namespace.

See h10n.helper.pluralize.Pluralize as helper example.

>>> locale = Locale('en-US', None, {})
>>> helpers = {'pluralize': 'h10n.helper.pluralize:Pluralize'}
>>> h = HelperNamespace(locale, helpers)
>>> h.pluralize                                  
<h10n.helper.pluralize.Pluralize object at ...>
>>> h2 = HelperNamespace(locale, helpers)
>>> h.pluralize is h2.pluralize
True

Project Versions

Previous topic

h10n.translator

Next topic

h10n.source

This Page