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 = None
125 ISO-15924 4-letter script code
126 property name
128 English name of the script
129 Country
131 babelfish.country.COUNTRIES
132 Country code to country name mapping
133 babelfish.country.COUNTRY_MATRIX
135 List of countries in the ISO-3166-1 as namedtuple of alpha2 and
136 name
137 class babelfish.country.CountryConverterManager
139 ConverterManager for country converters
140 babelfish.country.COUNTRY_CONVERTERS
142 Instance of CountryConverterManager
143 class babelfish.country.CountryMeta
145 The Country metaclass
146 Dynamically redirect Country.frommycode() to Country.fromcode()
148 with the mycode converter
149 class babelfish.country.Country(country)
151 A country on Earth
152 A country is represented by a 2-letter code from the ISO-3166
154 standard
155 Parameters
157 country (string) -- 2-letter ISO-3166 country code
158 alpha2 = None
160 ISO-3166 2-letter country code
161 classmethod fromcode(code, converter)
163 Create a Country by its code using converter to reverse()
164 it
165 Parameters
167 · code (string) -- the code to reverse
169 · converter (string) -- name of the CountryRever‐
171 seConverter to use
172 Returns
174 the corresponding Country instance
175 Return type
177 Country
178 Language
180 babelfish.language.LANGUAGES
181 Available language codes
182 babelfish.language.LANGUAGE_MATRIX
184 List of languages in the ISO-639-3 as namedtuple of alpha3,
185 alpha3b, alpha3t, alpha2, scope, type, name and comment
186 class babelfish.language.LanguageConverterManager
188 ConverterManager for language converters
189 babelfish.language.LANGUAGE_CONVERTERS
191 Instance of LanguageConverterManager
192 class babelfish.language.LanguageMeta
194 The Language metaclass
195 Dynamically redirect Language.frommycode() to
197 Language.fromcode() with the mycode converter
198 class babelfish.language.Language(language, country=None, script=None,
200 unknown=None)
201 A human language
202 A human language is composed of a language part following the
204 ISO-639 standard and can be country-specific when a Country is
205 specified.
206 The Language is extensible with custom converters (see cus‐
208 tom_converters)
209 Parameters
211 · language (string) -- the language as a 3-letter
213 ISO-639-3 code
214 · country (string or Country or None) -- the country (if
216 any) as a 2-letter ISO-3166 code or Country instance
217 · script (string or Script or None) -- the script (if
219 any) as a 4-letter ISO-15924 code or Script instance
220 · unknown (string or None) -- the unknown language as a
222 three-letters ISO-639-3 code to use as fallback
223 Raise ValueError if the language could not be recognized and
225 unknown is None
226 classmethod fromcode(code, converter)
228 Create a Language by its code using converter to
229 reverse() it
230 Parameters
232 · code (string) -- the code to reverse
234 · converter (string) -- name of the LanguageRever‐
236 seConverter to use
237 Returns
239 the corresponding Language instance
240 Return type
242 Language
243 classmethod fromietf(ietf)
245 Create a Language by from an IETF language code
246 Parameters
248 ietf (string) -- the ietf code
249 Returns
251 the corresponding Language instance
252 Return type
254 Language
255 Converter Bases
257 class babelfish.converters.LanguageConverter
258 A LanguageConverter supports converting an alpha3 language code
259 with an alpha2 country code and a script code into a custom code
260 codes Set of possible custom codes
262 convert(alpha3, country=None, script=None)
264 Convert an alpha3 language code with an alpha2 country
265 code and a script code into a custom code
266 Parameters
268 · alpha3 (string) -- ISO-639-3 language code
270 · country (string or None) -- ISO-3166 country
272 code, if any
273 · script (string or None) -- ISO-15924 script
275 code, if any
276 Returns
278 the corresponding custom code
279 Return type
281 string
282 Raise LanguageConvertError
284 class babelfish.converters.LanguageReverseConverter
286 A LanguageConverter able to reverse a custom code into a alpha3
287 ISO-639-3 language code, alpha2 ISO-3166-1 country code and
288 ISO-15924 script code
289 reverse(code)
291 Reverse a custom code into alpha3, country and script
292 code
293 Parameters
295 code (string) -- custom code to reverse
296 Returns
298 the corresponding alpha3 ISO-639-3 language code,
299 alpha2 ISO-3166-1 country code and ISO-15924
300 script code
301 Return type
303 tuple
304 Raise LanguageReverseError
306 class babelfish.converters.LanguageEquivalenceConverter
308 A LanguageEquivalenceConverter is a utility class that allows
309 you to easily define a LanguageReverseConverter by only specify‐
310 ing the dict from alpha3 to their corresponding symbols.
311 You must specify the dict of equivalence as a class variable
313 named SYMBOLS.
314 If you also set the class variable CASE_SENSITIVE to True then
316 the reverse conversion function will be case-sensitive (it is
317 case-insensitive by default).
318 Example:
320 class MyCodeConverter(babelfish.LanguageEquivalenceConverter):
322 CASE_SENSITIVE = True
323 SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
324 convert(alpha3, country=None, script=None)
326 Convert an alpha3 language code with an alpha2 country
327 code and a script code into a custom code
328 Parameters
330 · alpha3 (string) -- ISO-639-3 language code
332 · country (string or None) -- ISO-3166 country
334 code, if any
335 · script (string or None) -- ISO-15924 script
337 code, if any
338 Returns
340 the corresponding custom code
341 Return type
343 string
344 Raise LanguageConvertError
346 reverse(code)
348 Reverse a custom code into alpha3, country and script
349 code
350 Parameters
352 code (string) -- custom code to reverse
353 Returns
355 the corresponding alpha3 ISO-639-3 language code,
356 alpha2 ISO-3166-1 country code and ISO-15924
357 script code
358 Return type
360 tuple
361 Raise LanguageReverseError
363 class babelfish.converters.CountryConverter
365 A CountryConverter supports converting an alpha2 country code
366 into a custom code
367 codes Set of possible custom codes
369 convert(alpha2)
371 Convert an alpha2 country code into a custom code
372 Parameters
374 alpha2 (string) -- ISO-3166-1 language code
375 Returns
377 the corresponding custom code
378 Return type
380 string
381 Raise CountryConvertError
383 class babelfish.converters.CountryReverseConverter
385 A CountryConverter able to reverse a custom code into a alpha2
386 ISO-3166-1 country code
387 reverse(code)
389 Reverse a custom code into alpha2 code
390 Parameters
392 code (string) -- custom code to reverse
393 Returns
395 the corresponding alpha2 ISO-3166-1 country code
396 Return type
398 string
399 Raise CountryReverseError
401 class babelfish.converters.ConverterManager
403 Manager for babelfish converters behaving like a dict with lazy
404 loading
405 Loading is done in this order:
407 · Entry point converters
409 · Registered converters
411 · Internal converters
413 entry_point
415 The entry point where to look for converters
416 internal_converters
418 Internal converters with entry point syntax
419 registered_converters = None
421 Registered converters with entry point syntax
422 converters = None
424 Loaded converters
425 register(entry_point)
427 Register a converter
428 Parameters
430 entry_point (string) -- converter to register
431 (entry point syntax)
432 Raise ValueError if already registered
434 unregister(entry_point)
436 Unregister a converter
437 Parameters
439 entry_point (string) -- converter to unregister
440 (entry point syntax)
441 Exceptions
443 class babelfish.exceptions.Error
444 Base class for all exceptions in babelfish
445 class babelfish.exceptions.LanguageConvertError(alpha3, country=None,
447 script=None)
448 Exception raised by converters when convert() fails
449 Parameters
451 · alpha3 (string) -- alpha3 code that failed conversion
453 · country (string or None) -- country code that failed
455 conversion, if any
456 · script (string or None) -- script code that failed con‐
458 version, if any
459 class babelfish.exceptions.LanguageReverseError(code)
461 Exception raised by converters when reverse() fails
462 Parameters
464 code (string) -- code that failed reverse conversion
465 class babelfish.exceptions.CountryConvertError(alpha2)
467 Exception raised by converters when convert() fails
468 Parameters
470 alpha2 (string) -- alpha2 code that failed conversion
471 class babelfish.exceptions.CountryReverseError(code)
473 Exception raised by converters when reverse() fails
474 Parameters
476 code (string) -- code that failed reverse conversion
477
479 release date: 2015-10-31
480 · Fix hasattr on Country object when called with an invalid attribute
482
484 release date: 2015-01-24
485 · Fix setuptools deprecation warning
487
489 release date: 2014-06-22
490 · Better equality semantics for Language, Country, Script
492
494 release date: 2014-05-25
495 · Babelfish objects (Language, Country, Script) are now picklable
497 · Added support for Python 3.4
499
501 release date: 2014-01-26
502 · Add a register method to ConverterManager to register without loading
504
506 release date: 2014-01-25
507 WARNING: Backward incompatible changes
509 · Simplify converter management with ConverterManager class
511 · Make babelfish usable in place
513 · Add Python 2.6 / 3.2 compatibility
515
517 release date: 2013-11-21
518 WARNING: Backward incompatible changes
520 · Add converter support for Country
522 · Language/country reverse name detection is now case-insensitive
524 · Add alpha3t, scope and type converters
526 · Use lazy loading of converters
528
530 release date: 2013-11-09
531 · Add support for scripts
533 · Improve built-in converters
535 · Add support for ietf
537
539 release date: 2013-11-03
540 · Fix reading of data files
542
544 release date: 2013-10-31
545 · Add str method
547 · More explicit exceptions
549 · Change repr format to use ascii only
551
553 release date: 2013-10-21
554 · Add a fromcode method on Language class
556 · Add a codes attribute on converters
558
560 release date: 2013-10-20
561 · Fix converters not raising NoConversionError
563
565 release date: 2013-09-29
566 · Fix source distribution
568
570 release date: 2013-09-29
571 · Add missing files to source distribution
573
575 release date: 2013-09-28
576 · Fix python3 support
578
580 release date: 2013-09-28
581 · Initial version
583
585 Antoine Bertin
586
588 2019 the BabelFish authors
5890.5.5-dev Jul 26, 2019 BABELFISH(1)