babelfish man page

babelfish — babelfish Documentation

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.

Script

babelfish.script.SCRIPTS
Dictionary of script ISO-15924 codes to English names
class babelfish.script.Script(script)

A human writing system

A script is represented by a 4-letter code from the ISO-15924 standard

Parameters
script (string) -- 4-letter ISO-15924 script code
code = None
ISO-15924 4-letter script code
name
English name of the script

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 metaclass

Dynamically redirect Country.frommycode() to Country.fromcode() with the mycode converter
class babelfish.country.Country(country)

A country on Earth

A country is represented by a 2-letter code from the ISO-3166 standard

Parameters
country (string) -- 2-letter ISO-3166 country code
alpha2 = None
ISO-3166 2-letter country code
classmethod fromcode(code, converter)

Create a Country by its code using converter to reverse() it

Parameters
·
code (string) -- the code to reverse
·
converter (string) -- name of the CountryReverseConverter to use
Returns
the corresponding Country instance
Return type
Country

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 metaclass

Dynamically redirect Language.frommycode() to Language.fromcode() with the mycode 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 or Country instance
·
script (string or Script or None) -- the script (if any) as a 4-letter ISO-15924 code or Script 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 to reverse() it

Parameters
·
code (string) -- the code to reverse
·
converter (string) -- name of the LanguageReverseConverter to use
Returns
the corresponding Language instance
Return type
Language
classmethod fromietf(ietf)

Create a Language by from an IETF language code

Parameters
ietf (string) -- the ietf code
Returns
the corresponding Language instance
Return type
Language

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
LanguageConvertError
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 a LanguageReverseConverter 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() fails

Parameters
·
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() fails

Parameters
code (string) -- code that failed reverse conversion
class babelfish.exceptions.CountryConvertError(alpha2)

Exception raised by converters when convert() fails

Parameters
alpha2 (string) -- alpha2 code that failed conversion
class babelfish.exceptions.CountryReverseError(code)

Exception raised by converters when reverse() fails

Parameters
code (string) -- code that failed reverse conversion

0.5.5

release date: 2015-10-31

·
Fix hasattr on Country object when called with an invalid attribute

0.5.4

release date: 2015-01-24

·
Fix setuptools deprecation warning

0.5.3

release date: 2014-06-22

·
Better equality semantics for Language, Country, Script

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

release date: 2013-11-03

·
Fix reading of data files

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

0.1.4

release date: 2013-10-20

·
Fix converters not raising NoConversionError

0.1.3

release date: 2013-09-29

·
Fix source distribution

0.1.2

release date: 2013-09-29

·
Add missing files to source distribution

0.1.1

release date: 2013-09-28

·
Fix python3 support

0.1

release date: 2013-09-28

·
Initial version

Author

Antoine Bertin

Info

Jul 19, 2016 0.5.5-dev babelfish