
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.

* Script

* Country

* Language

* Converter Bases

* Exceptions


Changelog
*********


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
