Class EggTranslations

Overrides: object.__init__

(inherited documentation)

1. Calls the pkg_resources.add_activation_listener method passing the EggTranslations._parseINIFiles method as the callback. See the parseINIFiles method for more info on loading resources and gettext translation files.
2. Calls the EggTranslations setLocaleSet method passing the localeSet param. See the setLocaleSet method documentation for more info.

The initialize method sets the locale set and loads the resource and translation caches.

It must be called before using the EggTranslations API.

Parameters:

• localeSet (ASCII str or unicode or list containing ASCII str or unicode values) - A unicode or str or list containing locale country and language codes. The value(s) must be able to be converted to ASCII.

• iniFileName (ASCII str or unicode) - The name of the resource ini file in the egg's info directory.

  This file contains the location of localized and non-localized resources as well as translation files in gettext mo format. The default value for this file is "resources.ini". If a str is passed it must be able to be converted to unicode using the encoding passed to the initialize method. The default encoding is "UTF-8".
• encoding (ASCII str or unicode) - The character set encoding of the iniFileName. This encoding will be used to convert str values contained in the iniFileName to unicode. The default encoding is "UTF-8".
• fallback (boolean) - Indicates whether locale set fallback should take place. If set to True, the EggTranslations will search all locales in the locale set till a resource or gettext mo translation file is found. If set to False the EggTranslations will only try to locate a resource or gettext mo translation file for the current locale which is the first locale in the locale set.

Raises:

• INIParsingException -
• LookupError -
• UnicodeDecodeError -
• UnicodeEncodeError -

returns True if a key was specified in one or more eggs resource ini files (default is "resource.ini") for the given project and name.

The locale is an optional argument. By default the locale set is searched in fallback order as well as the 'all' default locale (if fallback=True in the initialize or setLocaleSet method) until a key is found. If no key found the method returns False.

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"

Returns:

bool True if the name is found otherwise False

Raises:

• UnicodeDecodeError -
• UnicodeEncodeError -

Returns the unicode string value that was specified in one or more eggs resource ini files (default is "resource.ini") for the given project and name. or None if not found.

The locale is an optional argument. By default the locale set is searched in fallback order (if fallback=True in the initialize or setLocale method) until a key is found.

However, if a locale is specified the method will only search for a key in the resource ini files for the given locale.

Example:

     [MyProject::fr]
      myimage = /resources/imgs/myimage.png

  >>> print eggRMInstance.getValueForKey("MyProject",
  ...                               "myimage", "fr")
  /resource/imgs/myimage.png

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"

Returns:

unicode value or None if not found

Raises:

• UnicodeDecodeError -
• UnicodeEncodeError -

1. One or more resource ini files have an entry for the key contained in the name parameter.
2. The entry is a valid directory path.

The locale is an optional argument. By default the locale set is searched in fallback order (if fallback=True in the initialize or setLocale method) until a key is found. If no key found the method returns False.

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"

Returns:

bool True if the name is found and the entry for that name is a valid directory path in an egg otherwise False

Raises:

• UnicodeDecodeError -
• UnicodeEncodeError -

Returns a list of unicode values containing the names of files in the directory entry for the given project and name. The listDirectory method will not return the names of sub directories only files in the directory for the given project and name.

The locale is an optional argument. By default the locale set is searched in fallback order (if fallback=True in the initialize or setLocale method) until a key is found. If no key found the method returns False.

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"

Returns:

list of unicode filenames

Raises:

• UnicodeDecodeError -
• UnicodeEncodeError -
• NameError -
• OSError -

1. one or more resource ini files have an entry for the key contained in the name parameter.
2. The entry must be a valid path to a file in the same egg as resource ini.

Example:

       [MyProject::fr]
       myResource=/resources/myresource.png

  >>> print eggRMInstance.hasResource("MyProject",
  ...                                 "myResource", "fr")
  True

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"

Returns:

bool True if the name key points to at least one resource in an egg otherwise False.

Raises:

• UnicodeDecodeError -

• UnicodeEncodeError - The locale is an optional argument. By default the locale set is searched in fallback order (if fallback=True in the initialize or setLocale method) until a key is found. If no key found the method returns False.

  However, if a locale is specified the method will only search for a key in the resource ini files for the given locale.

Returns a file handle to the resource for the given project and name.

The locale is an optional argument. By default the locale set is searched in fallback order (if fallback=True in the initialize or setLocale method) until a key is found. If no key found the method returns False.

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"

Returns:

file handle to the resource

Raises:

• UnicodeDecodeError -
• UnicodeEncodeError -
• NameError -
• IOError -

Returns a generator containing a list of non-blank non-comment lines in a resource file for the given project and name.

The locale is an optional argument. By default the locale set is searched in fallback order (if fallback=True in the initialize or setLocale method) until a key is found. If no key found the method returns False.

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"
• encoding (ASCII str or unicode) - The character set encoding of the resource file. This encoding will be used to convert str values contained in the file to unicode. The default encoding is "UTF-8".

Returns:

generator list of non-blank non-comment unicode lines.

Raises:

• UnicodeDecodeError -
• UnicodeEncodeError -
• NameError -
• IOError -

• LookupError - Example:

  Imagine you have a resource.ini file that contains the following:

       [MyProject::all]
       myDocument = README.txt
  

  Then you might retrieve all lines from the ``README.txt`` file via:

     >>> lines = eggRMInstance.getResourceAsLines("MyProject",
     ...                                          "myDocument",
     ...                                          "all")
  
     >>> for line in lines:
     ...    print line
  

Returns a unicode string containing the contents of the resource file for the given project and name.

The locale is an optional argument. By default the locale set is searched in fallback order (if fallback=True in the initialize or setLocale method) until a key is found. If no key found the method returns False.

However, if a locale is specified the method will only search for a key in the resource ini files for the given locale.

Example:

     [MyProject::all]
     myDocument = README.txt

  >>> f = eggRMInstance.getResourceAsString("MyProject",
  ...                                       "myDocument",
  ...                                       "all")

  >>> f
  u'This is the text contained in the readme file'

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - Optional argument that if specified tells the method to only return True if key is present in one or more ini files for the given locale. This parameter if specified must contain a valid language / country locale i.e. "en_US" or "en"
• encoding (ASCII str or unicode) - The character set encoding of the resource file. This encoding will be used to convert str values contained in the file to unicode. The default encoding is "UTF-8".

Returns:

unicode contents of the resource file.

Raises:

• UnicodeDecodeError -
• UnicodeEncodeError -
• NameError -
• IOError -
• LookupError -

Returns a unicode string containing the localized value for key txt in the given project. The name parameter points to a key in a resource ini file that contain a value entry pointing to a gettext .mo resource in the same egg.

An optional additional argument can be specified as the default value to return if no localized is found.

The txt parameter will be returned by EggTranslations.getText if no localized value found for the txt parameter.

However, if the default value argument is passed, that value will be returned instead of text.

>>> eggRMInstance.getText("MyProject", "catalog",
...                       "Hello World")
u'Hello World'
>>>
>>> eggRMInstance.getText("MyProject", "catalog",
...                             "Hello World",
...                             None)
None
>>>

If fallback was set to True in the EggTranslations.initialize method or the EggTranslations.setLocaleSet method, the EggTranslations.getText method will search all locales in the locale set till a gettext mo translation is found for the txt parameter.

If fallback was set to False in the EggTranslations.initialize method or the EggTranslations.setLocaleSet method, the EggTranslations.getText method will only search the current locale, which is the first locale in the locale set for a gettext mo translation for the txt parameter.

Note that the "all" default locale can not contain any key value pairs that point to gettext .mo files.

If a .mo gettext value is found in the "all" default locale, the .mo file will not be loaded by the EggTranslations.

Example:

     [MyProject::fr]
     catalog = locale/fr/MyProject.mo

   >>> egRMInstance.initialize("fr")
   >>> eggRMInstance.getText("MyProject", "catalog",
   ...                       "Hello")
   u'Bonjour'

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.

• txt (ASCII str or unicode) - The default text string which is used as look up key to retrieve a localized value from a gettext .mo file.

  The default text string is usual the English version of the text. The .mo gettext files will contain localizations of the English version with the English version as the key.
• args (list) - An optional argument which if passed will be returned if no localzation found for txt. The type of the return value in the args list has no limitations.

Returns:

unicode localized text or either the original txt argument or the default value in args if no localization found.

Raises:

• UnicodeDecodeError -

Returns:

boolean True if fallback set to True in initialize or setLocaleSet methods otherwise False.

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

• name (ASCII str or unicode) - name is the key to lookup in a resource ini file to retrieve the value specifed. For example, myname = this is my value.

  The name must be either an ASCII str or unicode.
• locale (unicode or ASCII str) - The locale to scan for a gettext .mo translation. This parameter must contain a valid language / country locale i.e. "en_US" or "en".

Returns:

bool True if the .mo gettext file exists for the project, name, and locale otherwise False.

Parameters:

• project (ASCII str or unicode) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII str or unicode.

Returns:

list of str locale language / country codes.

Returns the unicode file name of the resource ini files. The default for the resource ini file is "resource.ini".

Returns:

unicode the name of the resource ini file.

Returns:

list of str locale language / country codes.

Resets the EggTranslations locale set list.

Resetting the locale set includes unloading all gettext .mo translations, loading the the gettext .mo translations for the current locale set, and setting the gettext locale fallback order if the fallback parameter is set to True.

Note the initial locale set for the EggTranslations must be set in the EggTranslations.initialize method.

Parameters:

• localeSet (ASCII str or unicode or list containing ASCII str or unicode values) - A unicode or str or list containing locale country and language codes. The value(s) must be able to be converted to ASCII.
• fallback (boolean) - Indicates whether locale set fallback should take place. If set to True, the EggTranslations will search all locales in the locale set till a resource or gettext mo translation file is found. If set to False the EggTranslations will only try to locate a resource or gettext mo translation file for the current locale which is the first locale in the locale set.

Raises:

• UnicodeEncodeError -
• NameError -

Normalizes the str locale to lower case all lang codes and upper case all country codes.

Thus if passed "Fr_cA" this method would return "fr_CA".

Parameters:

• locale (ASCII str) - a str locale

Returns:

str normalized version of the locale.

Returns True if the str locale passed has a valid form which is either lang code ("es") or lang code / country code ("es_UY").

Parameters:

• locale (ASCII str) - a str locale

Returns:

boolean True if locale has a valid form otherwise False

Adds the lang code, if not already present, to the localeSet as a fallback to the lang country code.

Parameters:

• localeSet (list) - a list containing ASCII str locales

Returns:

list containing original locale set str's and lang code fallbacks.

Returns a str representation of the EggTranslations's egg loading values suitable for debugging using print, the logging package, or a UI dialog box.

EggTranslations
=========================
   INI FILE: ResourceFileName (Encoding)
   LOCALE SET: [localeSetValues]
   FALLBACK: True | False

   EggName
   ===============================

      ProjectName
      ---------------------
        [LocaleName]
           entryKey=entryValue
           gettextKey=getTextMoFile (LOADED | NOT_LOADED)


Here's an additional example output using real values::

EggTranslations
=========================
   INI FILE: 'resources.ini' (UTF-8)
   LOCALE SET: ['fr_CA', 'fr']
   FALLBACK: True

   MyProject 0.1
   ===============================

      myProject
      -------------------------
        [all]
           splashScreenImage = imgs/splash.png
           readme = README.txt

      myAlternateProject
      -------------------------
        [all]
           splashScreenImage = alternate/imgs/splash.png
           readme=alternate/README.txt

   MyProject.fr 0.1
   ===============================

      myProject
      ------------------------
        [fr_CA]
           splashScreenImage = locale/fr/imgs/splash.png
           readme = locale/fr/README.txt
           catalog= locale/fr/myProject.mo (LOADED)

      myAlternateProject
      ------------------------
        [fr_CA]
           splashScreenImage = alternate/locale/fr/imgs/splash.png
           readme = alternate/locale/fr/README.txt
           catalog = alternate/locale/fr/myProject.mo (LOADED)

Returns:

str debug string of EggTranslations current configuration in the UTF-8 encoding.