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 name 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 = None
159 ISO-3166 2-letter country code
160 classmethod fromcode(code, converter)
162 Create a Country by its code using converter to reverse()
163 it
164 Parameters
166 · code (string) -- the code to reverse
168 · converter (string) -- name of the CountryRever‐
170 seConverter to use
171 Returns
173 the corresponding Country instance
174 Return type
176 Country
177 Language
179 babelfish.language.LANGUAGES
180 Available language codes
181 babelfish.language.LANGUAGE_MATRIX
183 List of languages in the ISO-639-3 as namedtuple of alpha3,
184 alpha3b, alpha3t, alpha2, scope, type, name and comment
185 class babelfish.language.LanguageConverterManager
187 ConverterManager for language converters
188 babelfish.language.LANGUAGE_CONVERTERS
190 Instance of LanguageConverterManager
191 class babelfish.language.LanguageMeta
193 The Language metaclass
194 Dynamically redirect Language.frommycode() to
196 Language.fromcode() with the mycode converter
197 class babelfish.language.Language(language, country=None, script=None,
199 unknown=None)
200 A human language
201 A human language is composed of a language part following the
203 ISO-639 standard and can be country-specific when a Country is
204 specified.
205 The Language is extensible with custom converters (see cus‐
207 tom_converters)
208 Parameters
210 · language (string) -- the language as a 3-letter
212 ISO-639-3 code
213 · country (string or Country or None) -- the country (if
215 any) as a 2-letter ISO-3166 code or Country instance
216 · script (string or Script or None) -- the script (if
218 any) as a 4-letter ISO-15924 code or Script instance
219 · unknown (string or None) -- the unknown language as a
221 three-letters ISO-639-3 code to use as fallback
222 Raise ValueError if the language could not be recognized and
224 unknown is None
225 classmethod fromcode(code, converter)
227 Create a Language by its code using converter to
228 reverse() it
229 Parameters
231 · code (string) -- the code to reverse
233 · converter (string) -- name of the LanguageRever‐
235 seConverter to use
236 Returns
238 the corresponding Language instance
239 Return type
241 Language
242 classmethod fromietf(ietf)
244 Create a Language by from an IETF language code
245 Parameters
247 ietf (string) -- the ietf code
248 Returns
250 the corresponding Language instance
251 Return type
253 Language
254 Converter Bases
256 class babelfish.converters.LanguageConverter
257 A LanguageConverter supports converting an alpha3 language code
258 with an alpha2 country code and a script code into a custom code
259 codes Set of possible custom codes
261 convert(alpha3, country=None, script=None)
263 Convert an alpha3 language code with an alpha2 country
264 code and a script code into a custom code
265 Parameters
267 · alpha3 (string) -- ISO-639-3 language code
269 · country (string or None) -- ISO-3166 country
271 code, if any
272 · script (string or None) -- ISO-15924 script
274 code, if any
275 Returns
277 the corresponding custom code
278 Return type
280 string
281 Raise LanguageConvertError
283 class babelfish.converters.LanguageReverseConverter
285 A LanguageConverter able to reverse a custom code into a alpha3
286 ISO-639-3 language code, alpha2 ISO-3166-1 country code and
287 ISO-15924 script code
288 reverse(code)
290 Reverse a custom code into alpha3, country and script
291 code
292 Parameters
294 code (string) -- custom code to reverse
295 Returns
297 the corresponding alpha3 ISO-639-3 language code,
298 alpha2 ISO-3166-1 country code and ISO-15924
299 script code
300 Return type
302 tuple
303 Raise LanguageReverseError
305 class babelfish.converters.LanguageEquivalenceConverter
307 A LanguageEquivalenceConverter is a utility class that allows
308 you to easily define a LanguageReverseConverter by only specify‐
309 ing the dict from alpha3 to their corresponding symbols.
310 You must specify the dict of equivalence as a class variable
312 named SYMBOLS.
313 If you also set the class variable CASE_SENSITIVE to True then
315 the reverse conversion function will be case-sensitive (it is
316 case-insensitive by default).
317 Example:
319 class MyCodeConverter(babelfish.LanguageEquivalenceConverter):
321 CASE_SENSITIVE = True
322 SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
323 convert(alpha3, country=None, script=None)
325 Convert an alpha3 language code with an alpha2 country
326 code and a script code into a custom code
327 Parameters
329 · alpha3 (string) -- ISO-639-3 language code
331 · country (string or None) -- ISO-3166 country
333 code, if any
334 · script (string or None) -- ISO-15924 script
336 code, if any
337 Returns
339 the corresponding custom code
340 Return type
342 string
343 Raise LanguageConvertError
345 reverse(code)
347 Reverse a custom code into alpha3, country and script
348 code
349 Parameters
351 code (string) -- custom code to reverse
352 Returns
354 the corresponding alpha3 ISO-639-3 language code,
355 alpha2 ISO-3166-1 country code and ISO-15924
356 script code
357 Return type
359 tuple
360 Raise LanguageReverseError
362 class babelfish.converters.CountryConverter
364 A CountryConverter supports converting an alpha2 country code
365 into a custom code
366 codes Set of possible custom codes
368 convert(alpha2)
370 Convert an alpha2 country code into a custom code
371 Parameters
373 alpha2 (string) -- ISO-3166-1 language code
374 Returns
376 the corresponding custom code
377 Return type
379 string
380 Raise CountryConvertError
382 class babelfish.converters.CountryReverseConverter
384 A CountryConverter able to reverse a custom code into a alpha2
385 ISO-3166-1 country code
386 reverse(code)
388 Reverse a custom code into alpha2 code
389 Parameters
391 code (string) -- custom code to reverse
392 Returns
394 the corresponding alpha2 ISO-3166-1 country code
395 Return type
397 string
398 Raise CountryReverseError
400 class babelfish.converters.ConverterManager
402 Manager for babelfish converters behaving like a dict with lazy
403 loading
404 Loading is done in this order:
406 · Entry point converters
408 · Registered converters
410 · Internal converters
412 entry_point
414 The entry point where to look for converters
415 internal_converters
417 Internal converters with entry point syntax
418 registered_converters = None
420 Registered converters with entry point syntax
421 converters = None
423 Loaded converters
424 register(entry_point)
426 Register a converter
427 Parameters
429 entry_point (string) -- converter to register
430 (entry point syntax)
431 Raise ValueError if already registered
433 unregister(entry_point)
435 Unregister a converter
436 Parameters
438 entry_point (string) -- converter to unregister
439 (entry point syntax)
440 Exceptions
442 class babelfish.exceptions.Error
443 Base class for all exceptions in babelfish
444 class babelfish.exceptions.LanguageConvertError(alpha3, country=None,
446 script=None)
447 Exception raised by converters when convert() fails
448 Parameters
450 · alpha3 (string) -- alpha3 code that failed conversion
452 · country (string or None) -- country code that failed
454 conversion, if any
455 · script (string or None) -- script code that failed con‐
457 version, if any
458 class babelfish.exceptions.LanguageReverseError(code)
460 Exception raised by converters when reverse() fails
461 Parameters
463 code (string) -- code that failed reverse conversion
464 class babelfish.exceptions.CountryConvertError(alpha2)
466 Exception raised by converters when convert() fails
467 Parameters
469 alpha2 (string) -- alpha2 code that failed conversion
470 class babelfish.exceptions.CountryReverseError(code)
472 Exception raised by converters when reverse() fails
473 Parameters
475 code (string) -- code that failed reverse conversion
476
478 release date: 2015-10-31
479 · Fix hasattr on Country object when called with an invalid attribute
481
483 release date: 2015-01-24
484 · Fix setuptools deprecation warning
486
488 release date: 2014-06-22
489 · Better equality semantics for Language, Country, Script
491
493 release date: 2014-05-25
494 · Babelfish objects (Language, Country, Script) are now picklable
496 · Added support for Python 3.4
498
500 release date: 2014-01-26
501 · Add a register method to ConverterManager to register without loading
503
505 release date: 2014-01-25
506 WARNING: Backward incompatible changes
508 · Simplify converter management with ConverterManager class
510 · Make babelfish usable in place
512 · Add Python 2.6 / 3.2 compatibility
514
516 release date: 2013-11-21
517 WARNING: Backward incompatible changes
519 · Add converter support for Country
521 · Language/country reverse name detection is now case-insensitive
523 · Add alpha3t, scope and type converters
525 · Use lazy loading of converters
527
529 release date: 2013-11-09
530 · Add support for scripts
532 · Improve built-in converters
534 · Add support for ietf
536
538 release date: 2013-11-03
539 · Fix reading of data files
541
543 release date: 2013-10-31
544 · Add str method
546 · More explicit exceptions
548 · Change repr format to use ascii only
550
552 release date: 2013-10-21
553 · Add a fromcode method on Language class
555 · Add a codes attribute on converters
557
559 release date: 2013-10-20
560 · Fix converters not raising NoConversionError
562
564 release date: 2013-09-29
565 · Fix source distribution
567
569 release date: 2013-09-29
570 · Add missing files to source distribution
572
574 release date: 2013-09-28
575 · Fix python3 support
577
579 release date: 2013-09-28
580 · Initial version
582
584 Antoine Bertin
585
587 2015 the BabelFish authors
5880.5.5-dev Feb 02, 2019 BABELFISH(1)