BabelFish¶
Release v0.5.5-dev
BabelFish is a Python library to work with countries and languages.
Script¶
Simple script representation from 4-letter code (ISO-15924):
>>> script = babelfish.Script('Hira')
>>> script
<Script [Hira]>
Country¶
Simple country representation from 2-letter code (ISO-3166):
>>> country = babelfish.Country('GB')
>>> country
<Country [GB]>
Built-in country converters (name):
>>> country.name
'UNITED KINGDOM'
Language¶
Simple language representation from 3-letter code (ISO-639-3):
>>> language = babelfish.Language('eng')
>>> language
<Language [en]>
Country specific language:
>>> language = babelfish.Language('por', 'BR')
>>> language
<Language [pt-BR]>
Language with specific script:
>>> language = babelfish.Language.fromalpha2('sr')
>>> language.script = babelfish.Script('Cyrl')
>>> language
<Language [sr-Cyrl]>
Built-in language converters (alpha2, alpha3b, alpha3t, name, scope, type and opensubtitles):
>>> language = babelfish.Language('por', 'BR')
>>> language.alpha2
'pt'
>>> language.scope
'individual'
>>> language.type
'living'
>>> language.opensubtitles
'pob'
>>> babelfish.Language.fromalpha3b('fre')
<Language [fr]>
Custom Converters¶
Build your own Language/Country converter:
class MyCodeConverter(babelfish.LanguageReverseConverter):
def __init__(self):
self.to_mycode = {'fra': 'mycode1', 'eng': 'mycode2'}
self.from_mycode = {'mycode1': 'fra', 'mycode2': 'eng'}
def convert(self, alpha3, country=None, script=None):
if alpha3 not in self.to_mycode:
raise babelfish.LanguageConvertError(alpha3, country, script)
return self.to_mycode[alpha3]
def reverse(self, mycode):
if mycode not in self.from_mycode:
raise babelfish.LanguageReverseError(mycode)
return (self.from_mycode[mycode],)
You can also use the LanguageEquivalenceConverter
utility class if your mapping is a simple one-to-one mapping:
class MyCodeConverter(babelfish.LanguageEquivalenceConverter):
SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
Use it directly (no lazy loading):
>>> babelfish.LANGUAGE_CONVERTERS['mycode'] = MyCodeConverter()
>>> babelfish.Language.frommycode('mycode2')
<Language [en]>
>>> babelfish.Language('fra').mycode
'mycode1'
Or make it available in your application by using the entry point (lazy loading):
setup([...],
entry_points={'babelfish.language_converters': ['mycode = mymodule.converter:MyCodeConverter']},
[...])
Or if you don’t want to use the entry point (lazy loading):
>>> babelfish.language_converters.register('mycode = mymodule.converter:MyCodeConverter')
API Documentation¶
If you are looking for information on a specific function, class or method, this part of the documentation is for you.
Country¶
-
babelfish.country.
COUNTRIES
¶ Country code to country name mapping
-
babelfish.country.
COUNTRY_MATRIX
¶ List of countries in the ISO-3166-1 as namedtuple of alpha2 and name
-
class
babelfish.country.
CountryConverterManager
¶ ConverterManager
for country converters
-
babelfish.country.
COUNTRY_CONVERTERS
¶ Instance of
CountryConverterManager
-
class
babelfish.country.
CountryMeta
¶ The
Country
metaclassDynamically redirect
Country.frommycode()
toCountry.fromcode()
with themycode
converter
Language¶
-
babelfish.language.
LANGUAGES
¶ Available language codes
-
babelfish.language.
LANGUAGE_MATRIX
¶ List of languages in the ISO-639-3 as namedtuple of alpha3, alpha3b, alpha3t, alpha2, scope, type, name and comment
-
class
babelfish.language.
LanguageConverterManager
¶ ConverterManager
for language converters
-
babelfish.language.
LANGUAGE_CONVERTERS
¶ Instance of
LanguageConverterManager
-
class
babelfish.language.
LanguageMeta
¶ The
Language
metaclassDynamically redirect
Language.frommycode()
toLanguage.fromcode()
with themycode
converter
-
class
babelfish.language.
Language
(language, country=None, script=None, unknown=None)¶ A human language
A human language is composed of a language part following the ISO-639 standard and can be country-specific when a
Country
is specified.The
Language
is extensible with custom converters (see Custom Converters)Parameters: - language (string) – the language as a 3-letter ISO-639-3 code
- country (string or
Country
or None) – the country (if any) as a 2-letter ISO-3166 code orCountry
instance - script (string or
Script
or None) – the script (if any) as a 4-letter ISO-15924 code orScript
instance - unknown (string or None) – the unknown language as a three-letters ISO-639-3 code to use as fallback
Raise: ValueError if the language could not be recognized and unknown is
None
-
classmethod
fromcode
(code, converter)¶ Create a
Language
by its code using converter toreverse()
itParameters: - code (string) – the code to reverse
- converter (string) – name of the
LanguageReverseConverter
to use
Returns: the corresponding
Language
instanceReturn type:
Converter Bases¶
-
class
babelfish.converters.
LanguageConverter
¶ A
LanguageConverter
supports converting an alpha3 language code with an alpha2 country code and a script code into a custom code-
codes
¶ Set of possible custom codes
-
convert
(alpha3, country=None, script=None)¶ Convert an alpha3 language code with an alpha2 country code and a script code into a custom code
Parameters: - alpha3 (string) – ISO-639-3 language code
- country (string or None) – ISO-3166 country code, if any
- script (string or None) – ISO-15924 script code, if any
Returns: the corresponding custom code
Return type: string
Raise:
-
-
class
babelfish.converters.
LanguageReverseConverter
¶ A
LanguageConverter
able to reverse a custom code into a alpha3 ISO-639-3 language code, alpha2 ISO-3166-1 country code and ISO-15924 script code-
reverse
(code)¶ Reverse a custom code into alpha3, country and script code
Parameters: code (string) – custom code to reverse Returns: the corresponding alpha3 ISO-639-3 language code, alpha2 ISO-3166-1 country code and ISO-15924 script code Return type: tuple Raise: LanguageReverseError
-
-
class
babelfish.converters.
LanguageEquivalenceConverter
¶ A
LanguageEquivalenceConverter
is a utility class that allows you to easily define aLanguageReverseConverter
by only specifying the dict from alpha3 to their corresponding symbols.You must specify the dict of equivalence as a class variable named SYMBOLS.
If you also set the class variable CASE_SENSITIVE to
True
then the reverse conversion function will be case-sensitive (it is case-insensitive by default).Example:
class MyCodeConverter(babelfish.LanguageEquivalenceConverter): CASE_SENSITIVE = True SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
-
class
babelfish.converters.
CountryConverter
¶ A
CountryConverter
supports converting an alpha2 country code into a custom code-
codes
¶ Set of possible custom codes
-
convert
(alpha2)¶ Convert an alpha2 country code into a custom code
Parameters: alpha2 (string) – ISO-3166-1 language code Returns: the corresponding custom code Return type: string Raise: CountryConvertError
-
-
class
babelfish.converters.
CountryReverseConverter
¶ A
CountryConverter
able to reverse a custom code into a alpha2 ISO-3166-1 country code-
reverse
(code)¶ Reverse a custom code into alpha2 code
Parameters: code (string) – custom code to reverse Returns: the corresponding alpha2 ISO-3166-1 country code Return type: string Raise: CountryReverseError
-
-
class
babelfish.converters.
ConverterManager
¶ Manager for babelfish converters behaving like a dict with lazy loading
Loading is done in this order:
- Entry point converters
- Registered converters
- Internal converters
-
entry_point
¶ The entry point where to look for converters
-
internal_converters
¶ Internal converters with entry point syntax
-
registered_converters
= None¶ Registered converters with entry point syntax
-
converters
= None¶ Loaded converters
-
register
(entry_point)¶ Register a converter
Parameters: entry_point (string) – converter to register (entry point syntax) Raise: ValueError if already registered
-
unregister
(entry_point)¶ Unregister a converter
Parameters: entry_point (string) – converter to unregister (entry point syntax)
Exceptions¶
-
class
babelfish.exceptions.
Error
¶ Base class for all exceptions in babelfish
-
class
babelfish.exceptions.
LanguageConvertError
(alpha3, country=None, script=None)¶ Exception raised by converters when
convert()
failsParameters: - alpha3 (string) – alpha3 code that failed conversion
- country (string or None) – country code that failed conversion, if any
- script (string or None) – script code that failed conversion, if any
-
class
babelfish.exceptions.
LanguageReverseError
(code)¶ Exception raised by converters when
reverse()
failsParameters: code (string) – code that failed reverse conversion
Changelog¶
0.5.2¶
release date: 2014-05-25
- Babelfish objects (Language, Country, Script) are now picklable
- Added support for Python 3.4
0.5.1¶
release date: 2014-01-26
- Add a register method to ConverterManager to register without loading
0.5.0¶
release date: 2014-01-25
WARNING: Backward incompatible changes
- Simplify converter management with ConverterManager class
- Make babelfish usable in place
- Add Python 2.6 / 3.2 compatibility
0.4.0¶
release date: 2013-11-21
WARNING: Backward incompatible changes
- Add converter support for Country
- Language/country reverse name detection is now case-insensitive
- Add alpha3t, scope and type converters
- Use lazy loading of converters
0.3.0¶
release date: 2013-11-09
- Add support for scripts
- Improve built-in converters
- Add support for ietf
0.2.0¶
release date: 2013-10-31
- Add str method
- More explicit exceptions
- Change repr format to use ascii only
0.1.5¶
release date: 2013-10-21
- Add a fromcode method on Language class
- Add a codes attribute on converters