1BABELFISH(1) babelfish BABELFISH(1)
2
6 babelfish - babelfish Documentation
7 Release v0.5.5-dev
9 BabelFish is a Python library to work with countries and languages.
11
13 Simple script representation from 4-letter code (ISO-15924):
14 >>> script = babelfish.Script('Hira')
16 >>> script
17 <Script [Hira]>
18
20 Simple country representation from 2-letter code (ISO-3166):
21 >>> country = babelfish.Country('GB')
23 >>> country
24 <Country [GB]>
25 Built-in country converters (name):
27 >>> country.name
29 'UNITED KINGDOM'
30
32 Simple language representation from 3-letter code (ISO-639-3):
33 >>> language = babelfish.Language('eng')
35 >>> language
36 <Language [en]>
37 Country specific language:
39 >>> language = babelfish.Language('por', 'BR')
41 >>> language
42 <Language [pt-BR]>
43 Language with specific script:
45 >>> language = babelfish.Language.fromalpha2('sr')
47 >>> language.script = babelfish.Script('Cyrl')
48 >>> language
49 <Language [sr-Cyrl]>
50 Built-in language converters (alpha2, alpha3b, alpha3t, name, scope,
52 type and opensubtitles):
53 >>> language = babelfish.Language('por', 'BR')
55 >>> language.alpha2
56 'pt'
57 >>> language.scope
58 'individual'
59 >>> language.type
60 'living'
61 >>> language.opensubtitles
62 'pob'
63 >>> babelfish.Language.fromalpha3b('fre')
64 <Language [fr]>
65
67 Build your own Language/Country converter:
68 class MyCodeConverter(babelfish.LanguageReverseConverter):
70 def __init__(self):
71 self.to_mycode = {'fra': 'mycode1', 'eng': 'mycode2'}
72 self.from_mycode = {'mycode1': 'fra', 'mycode2': 'eng'}
73 def convert(self, alpha3, country=None, script=None):
74 if alpha3 not in self.to_mycode:
75 raise babelfish.LanguageConvertError(alpha3, country, script)
76 return self.to_mycode[alpha3]
77 def reverse(self, mycode):
78 if mycode not in self.from_mycode:
79 raise babelfish.LanguageReverseError(mycode)
80 return (self.from_mycode[mycode],)
81 You can also use the LanguageEquivalenceConverter utility class if your
83 mapping is a simple one-to-one mapping:
84 class MyCodeConverter(babelfish.LanguageEquivalenceConverter):
86 SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
87 Use it directly (no lazy loading):
89 >>> babelfish.LANGUAGE_CONVERTERS['mycode'] = MyCodeConverter()
91 >>> babelfish.Language.frommycode('mycode2')
92 <Language [en]>
93 >>> babelfish.Language('fra').mycode
94 'mycode1'
95 Or make it available in your application by using the entry point (lazy
97 loading):
98 setup([...],
100 entry_points={'babelfish.language_converters': ['mycode = mymodule.converter:MyCodeConverter']},
101 [...])
102 Or if you don't want to use the entry point (lazy loading):
104 >>> babelfish.language_converters.register('mycode = mymodule.converter:MyCodeConverter')
106
108 If you are looking for information on a specific function, class or
109 method, this part of the documentation is for you.
110 Script
112 babelfish.script.SCRIPTS
113 Dictionary of script ISO-15924 codes to English names
114 class babelfish.script.Script(script)
116 A human writing system
117 A script is represented by a 4-letter code from the ISO-15924
119 standard
120 Parameters
122 script (string) -- 4-letter ISO-15924 script code
123 code ISO-15924 4-letter script code
125 property name
127 English name of the script
128 Country
130 babelfish.country.COUNTRIES
131 Country code to country name mapping
132 babelfish.country.COUNTRY_MATRIX
134 List of countries in the ISO-3166-1 as namedtuple of alpha2 and
135 name
136 class babelfish.country.CountryConverterManager
138 ConverterManager for country converters
139 babelfish.country.COUNTRY_CONVERTERS
141 Instance of CountryConverterManager
142 class babelfish.country.CountryMeta
144 The Country metaclass
145 Dynamically redirect Country.frommycode() to Country.fromcode()
147 with the mycode converter
148 class babelfish.country.Country(country)
150 A country on Earth
151 A country is represented by a 2-letter code from the ISO-3166
153 standard
154 Parameters
156 country (string) -- 2-letter ISO-3166 country code
157 alpha2 ISO-3166 2-letter country code
159 classmethod fromcode(code, converter)
161 Create a Country by its code using converter to reverse()
162 it
163 Parameters
165 • code (string) -- the code to reverse
167 • converter (string) -- name of the CountryRever‐
169 seConverter to use
170 Returns
172 the corresponding Country instance
173 Return type
175 Country
176 Language
178 babelfish.language.LANGUAGES
179 Available language codes
180 babelfish.language.LANGUAGE_MATRIX
182 List of languages in the ISO-639-3 as namedtuple of alpha3, al‐
183 pha3b, alpha3t, alpha2, scope, type, name and comment
184 class babelfish.language.LanguageConverterManager
186 ConverterManager for language converters
187 babelfish.language.LANGUAGE_CONVERTERS
189 Instance of LanguageConverterManager
190 class babelfish.language.LanguageMeta
192 The Language metaclass
193 Dynamically redirect Language.frommycode() to
195 Language.fromcode() with the mycode converter
196 class babelfish.language.Language(language, country=None, script=None,
198 unknown=None)
199 A human language
200 A human language is composed of a language part following the
202 ISO-639 standard and can be country-specific when a Country is
203 specified.
204 The Language is extensible with custom converters (see cus‐
206 tom_converters)
207 Parameters
209 • language (string) -- the language as a 3-letter
211 ISO-639-3 code
212 • country (string or Country or None) -- the country (if
214 any) as a 2-letter ISO-3166 code or Country instance
215 • script (string or Script or None) -- the script (if
217 any) as a 4-letter ISO-15924 code or Script instance
218 • unknown (string or None) -- the unknown language as a
220 three-letters ISO-639-3 code to use as fallback
221 Raise ValueError if the language could not be recognized and
223 unknown is None
224 classmethod fromcode(code, converter)
226 Create a Language by its code using converter to re‐
227 verse() it
228 Parameters
230 • code (string) -- the code to reverse
232 • converter (string) -- name of the LanguageRever‐
234 seConverter to use
235 Returns
237 the corresponding Language instance
238 Return type
240 Language
241 classmethod fromietf(ietf)
243 Create a Language by from an IETF language code
244 Parameters
246 ietf (string) -- the ietf code
247 Returns
249 the corresponding Language instance
250 Return type
252 Language
253 Converter Bases
255 class babelfish.converters.LanguageConverter
256 A LanguageConverter supports converting an alpha3 language code
257 with an alpha2 country code and a script code into a custom code
258 codes Set of possible custom codes
260 convert(alpha3, country=None, script=None)
262 Convert an alpha3 language code with an alpha2 country
263 code and a script code into a custom code
264 Parameters
266 • alpha3 (string) -- ISO-639-3 language code
268 • country (string or None) -- ISO-3166 country
270 code, if any
271 • script (string or None) -- ISO-15924 script
273 code, if any
274 Returns
276 the corresponding custom code
277 Return type
279 string
280 Raise LanguageConvertError
282 class babelfish.converters.LanguageReverseConverter
284 A LanguageConverter able to reverse a custom code into a alpha3
285 ISO-639-3 language code, alpha2 ISO-3166-1 country code and
286 ISO-15924 script code
287 reverse(code)
289 Reverse a custom code into alpha3, country and script
290 code
291 Parameters
293 code (string) -- custom code to reverse
294 Returns
296 the corresponding alpha3 ISO-639-3 language code,
297 alpha2 ISO-3166-1 country code and ISO-15924
298 script code
299 Return type
301 tuple
302 Raise LanguageReverseError
304 class babelfish.converters.LanguageEquivalenceConverter
306 A LanguageEquivalenceConverter is a utility class that allows
307 you to easily define a LanguageReverseConverter by only specify‐
308 ing the dict from alpha3 to their corresponding symbols.
309 You must specify the dict of equivalence as a class variable
311 named SYMBOLS.
312 If you also set the class variable CASE_SENSITIVE to True then
314 the reverse conversion function will be case-sensitive (it is
315 case-insensitive by default).
316 Example:
318 class MyCodeConverter(babelfish.LanguageEquivalenceConverter):
320 CASE_SENSITIVE = True
321 SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
322 convert(alpha3, country=None, script=None)
324 Convert an alpha3 language code with an alpha2 country
325 code and a script code into a custom code
326 Parameters
328 • alpha3 (string) -- ISO-639-3 language code
330 • country (string or None) -- ISO-3166 country
332 code, if any
333 • script (string or None) -- ISO-15924 script
335 code, if any
336 Returns
338 the corresponding custom code
339 Return type
341 string
342 Raise LanguageConvertError
344 reverse(code)
346 Reverse a custom code into alpha3, country and script
347 code
348 Parameters
350 code (string) -- custom code to reverse
351 Returns
353 the corresponding alpha3 ISO-639-3 language code,
354 alpha2 ISO-3166-1 country code and ISO-15924
355 script code
356 Return type
358 tuple
359 Raise LanguageReverseError
361 class babelfish.converters.CountryConverter
363 A CountryConverter supports converting an alpha2 country code
364 into a custom code
365 codes Set of possible custom codes
367 convert(alpha2)
369 Convert an alpha2 country code into a custom code
370 Parameters
372 alpha2 (string) -- ISO-3166-1 language code
373 Returns
375 the corresponding custom code
376 Return type
378 string
379 Raise CountryConvertError
381 class babelfish.converters.CountryReverseConverter
383 A CountryConverter able to reverse a custom code into a alpha2
384 ISO-3166-1 country code
385 reverse(code)
387 Reverse a custom code into alpha2 code
388 Parameters
390 code (string) -- custom code to reverse
391 Returns
393 the corresponding alpha2 ISO-3166-1 country code
394 Return type
396 string
397 Raise CountryReverseError
399 class babelfish.converters.ConverterManager
401 Manager for babelfish converters behaving like a dict with lazy
402 loading
403 Loading is done in this order:
405 • Entry point converters
407 • Registered converters
409 • Internal converters
411 entry_point
413 The entry point where to look for converters
414 internal_converters
416 Internal converters with entry point syntax
417 registered_converters
419 Registered converters with entry point syntax
420 converters
422 Loaded converters
423 register(entry_point)
425 Register a converter
426 Parameters
428 entry_point (string) -- converter to register (en‐
429 try point syntax)
430 Raise ValueError if already registered
432 unregister(entry_point)
434 Unregister a converter
435 Parameters
437 entry_point (string) -- converter to unregister
438 (entry point syntax)
439 Exceptions
441 class babelfish.exceptions.Error
442 Base class for all exceptions in babelfish
443 class babelfish.exceptions.LanguageConvertError(alpha3, country=None,
445 script=None)
446 Exception raised by converters when convert() fails
447 Parameters
449 • alpha3 (string) -- alpha3 code that failed conversion
451 • country (string or None) -- country code that failed
453 conversion, if any
454 • script (string or None) -- script code that failed con‐
456 version, if any
457 class babelfish.exceptions.LanguageReverseError(code)
459 Exception raised by converters when reverse() fails
460 Parameters
462 code (string) -- code that failed reverse conversion
463 class babelfish.exceptions.CountryConvertError(alpha2)
465 Exception raised by converters when convert() fails
466 Parameters
468 alpha2 (string) -- alpha2 code that failed conversion
469 class babelfish.exceptions.CountryReverseError(code)
471 Exception raised by converters when reverse() fails
472 Parameters
474 code (string) -- code that failed reverse conversion
475
477 release date: 2015-10-31
478 • Fix hasattr on Country object when called with an invalid attribute
480
482 release date: 2015-01-24
483 • Fix setuptools deprecation warning
485
487 release date: 2014-06-22
488 • Better equality semantics for Language, Country, Script
490
492 release date: 2014-05-25
493 • Babelfish objects (Language, Country, Script) are now picklable
495 • Added support for Python 3.4
497
499 release date: 2014-01-26
500 • Add a register method to ConverterManager to register without loading
502
504 release date: 2014-01-25
505 WARNING: Backward incompatible changes
507 • Simplify converter management with ConverterManager class
509 • Make babelfish usable in place
511 • Add Python 2.6 / 3.2 compatibility
513
515 release date: 2013-11-21
516 WARNING: Backward incompatible changes
518 • Add converter support for Country
520 • Language/country reverse name detection is now case-insensitive
522 • Add alpha3t, scope and type converters
524 • Use lazy loading of converters
526
528 release date: 2013-11-09
529 • Add support for scripts
531 • Improve built-in converters
533 • Add support for ietf
535
537 release date: 2013-11-03
538 • Fix reading of data files
540
542 release date: 2013-10-31
543 • Add str method
545 • More explicit exceptions
547 • Change repr format to use ascii only
549
551 release date: 2013-10-21
552 • Add a fromcode method on Language class
554 • Add a codes attribute on converters
556
558 release date: 2013-10-20
559 • Fix converters not raising NoConversionError
561
563 release date: 2013-09-29
564 • Fix source distribution
566
568 release date: 2013-09-29
569 • Add missing files to source distribution
571
573 release date: 2013-09-28
574 • Fix python3 support
576
578 release date: 2013-09-28
579 • Initial version
581
583 Antoine Bertin
584
586 2021 the BabelFish authors
5870.5.5-dev Jan 27, 2021 BABELFISH(1)