1BABELFISH(1)                       babelfish                      BABELFISH(1)
2
3
4

NAME

6       babelfish - babelfish Documentation
7
8       Release v0.5.5-dev
9
10       BabelFish is a Python library to work with countries and languages.
11

SCRIPT

13       Simple script representation from 4-letter code (ISO-15924):
14
15          >>> script = babelfish.Script('Hira')
16          >>> script
17          <Script [Hira]>
18

COUNTRY

20       Simple country representation from 2-letter code (ISO-3166):
21
22          >>> country = babelfish.Country('GB')
23          >>> country
24          <Country [GB]>
25
26       Built-in country converters (name):
27
28          >>> country.name
29          'UNITED KINGDOM'
30

LANGUAGE

32       Simple language representation from 3-letter code (ISO-639-3):
33
34          >>> language = babelfish.Language('eng')
35          >>> language
36          <Language [en]>
37
38       Country specific language:
39
40          >>> language = babelfish.Language('por', 'BR')
41          >>> language
42          <Language [pt-BR]>
43
44       Language with specific script:
45
46          >>> language = babelfish.Language.fromalpha2('sr')
47          >>> language.script = babelfish.Script('Cyrl')
48          >>> language
49          <Language [sr-Cyrl]>
50
51       Built-in  language  converters  (alpha2, alpha3b, alpha3t, name, scope,
52       type and opensubtitles):
53
54          >>> 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

CUSTOM CONVERTERS

67       Build your own Language/Country converter:
68
69          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
82       You can also use the LanguageEquivalenceConverter utility class if your
83       mapping is a simple one-to-one mapping:
84
85          class MyCodeConverter(babelfish.LanguageEquivalenceConverter):
86              SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
87
88       Use it directly (no lazy loading):
89
90          >>> babelfish.LANGUAGE_CONVERTERS['mycode'] = MyCodeConverter()
91          >>> babelfish.Language.frommycode('mycode2')
92          <Language [en]>
93          >>> babelfish.Language('fra').mycode
94          'mycode1'
95
96       Or make it available in your application by using the entry point (lazy
97       loading):
98
99          setup([...],
100                entry_points={'babelfish.language_converters': ['mycode = mymodule.converter:MyCodeConverter']},
101                [...])
102
103       Or if you don't want to use the entry point (lazy loading):
104
105          >>> babelfish.language_converters.register('mycode = mymodule.converter:MyCodeConverter')
106

API DOCUMENTATION

108       If you are looking for information on a  specific  function,  class  or
109       method, this part of the documentation is for you.
110
111   Script
112       babelfish.script.SCRIPTS
113              Dictionary of script ISO-15924 codes to English names
114
115       class babelfish.script.Script(script)
116              A human writing system
117
118              A  script  is  represented by a 4-letter code from the ISO-15924
119              standard
120
121              Parameters
122                     script (string) -- 4-letter ISO-15924 script code
123
124              code   ISO-15924 4-letter script code
125
126              property name
127                     English name of the script
128
129   Country
130       babelfish.country.COUNTRIES
131              Country code to country name mapping
132
133       babelfish.country.COUNTRY_MATRIX
134              List of countries in the ISO-3166-1 as namedtuple of alpha2  and
135              name
136
137       class babelfish.country.CountryConverterManager
138              ConverterManager for country converters
139
140       babelfish.country.COUNTRY_CONVERTERS
141              Instance of CountryConverterManager
142
143       class babelfish.country.CountryMeta
144              The Country metaclass
145
146              Dynamically  redirect Country.frommycode() to Country.fromcode()
147              with the mycode converter
148
149       class babelfish.country.Country(country)
150              A country on Earth
151
152              A country is represented by a 2-letter code  from  the  ISO-3166
153              standard
154
155              Parameters
156                     country (string) -- 2-letter ISO-3166 country code
157
158              alpha2 ISO-3166 2-letter country code
159
160              classmethod fromcode(code, converter)
161                     Create a Country by its code using converter to reverse()
162                     it
163
164                     Parameters
165
166code (string) -- the code to reverse
167
168converter (string) -- name of the  CountryRever‐
169                              seConverter to use
170
171                     Returns
172                            the corresponding Country instance
173
174                     Return type
175                            Country
176
177   Language
178       babelfish.language.LANGUAGES
179              Available language codes
180
181       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
185       class babelfish.language.LanguageConverterManager
186              ConverterManager for language converters
187
188       babelfish.language.LANGUAGE_CONVERTERS
189              Instance of LanguageConverterManager
190
191       class babelfish.language.LanguageMeta
192              The Language metaclass
193
194              Dynamically       redirect       Language.frommycode()        to
195              Language.fromcode() with the mycode converter
196
197       class  babelfish.language.Language(language, country=None, script=None,
198       unknown=None)
199              A human language
200
201              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
205              The Language is extensible  with  custom  converters  (see  cus‐
206              tom_converters)
207
208              Parameters
209
210language   (string)  --  the  language  as  a  3-letter
211                       ISO-639-3 code
212
213country (string or Country or None) -- the country  (if
214                       any) as a 2-letter ISO-3166 code or Country instance
215
216script  (string  or  Script  or None) -- the script (if
217                       any) as a 4-letter ISO-15924 code or Script instance
218
219unknown (string or None) -- the unknown language  as  a
220                       three-letters ISO-639-3 code to use as fallback
221
222              Raise  ValueError  if  the  language could not be recognized and
223                     unknown is None
224
225              classmethod fromcode(code, converter)
226                     Create a Language by its  code  using  converter  to  re‐
227                     verse() it
228
229                     Parameters
230
231code (string) -- the code to reverse
232
233converter (string) -- name of the LanguageRever‐
234                              seConverter to use
235
236                     Returns
237                            the corresponding Language instance
238
239                     Return type
240                            Language
241
242              classmethod fromietf(ietf)
243                     Create a Language by from an IETF language code
244
245                     Parameters
246                            ietf (string) -- the ietf code
247
248                     Returns
249                            the corresponding Language instance
250
251                     Return type
252                            Language
253
254   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
259              codes  Set of possible custom codes
260
261              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
265                     Parameters
266
267alpha3 (string) -- ISO-639-3 language code
268
269country (string or  None)  --  ISO-3166  country
270                              code, if any
271
272script  (string  or  None)  --  ISO-15924 script
273                              code, if any
274
275                     Returns
276                            the corresponding custom code
277
278                     Return type
279                            string
280
281                     Raise  LanguageConvertError
282
283       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
288              reverse(code)
289                     Reverse a custom code into  alpha3,  country  and  script
290                     code
291
292                     Parameters
293                            code (string) -- custom code to reverse
294
295                     Returns
296                            the  corresponding alpha3 ISO-639-3 language code,
297                            alpha2  ISO-3166-1  country  code  and   ISO-15924
298                            script code
299
300                     Return type
301                            tuple
302
303                     Raise  LanguageReverseError
304
305       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
310              You  must  specify  the  dict of equivalence as a class variable
311              named SYMBOLS.
312
313              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
317              Example:
318
319                 class MyCodeConverter(babelfish.LanguageEquivalenceConverter):
320                     CASE_SENSITIVE = True
321                     SYMBOLS = {'fra': 'mycode1', 'eng': 'mycode2'}
322
323              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
327                     Parameters
328
329alpha3 (string) -- ISO-639-3 language code
330
331country  (string  or  None)  -- ISO-3166 country
332                              code, if any
333
334script (string  or  None)  --  ISO-15924  script
335                              code, if any
336
337                     Returns
338                            the corresponding custom code
339
340                     Return type
341                            string
342
343                     Raise  LanguageConvertError
344
345              reverse(code)
346                     Reverse  a  custom  code  into alpha3, country and script
347                     code
348
349                     Parameters
350                            code (string) -- custom code to reverse
351
352                     Returns
353                            the corresponding alpha3 ISO-639-3 language  code,
354                            alpha2   ISO-3166-1  country  code  and  ISO-15924
355                            script code
356
357                     Return type
358                            tuple
359
360                     Raise  LanguageReverseError
361
362       class babelfish.converters.CountryConverter
363              A CountryConverter supports converting an  alpha2  country  code
364              into a custom code
365
366              codes  Set of possible custom codes
367
368              convert(alpha2)
369                     Convert an alpha2 country code into a custom code
370
371                     Parameters
372                            alpha2 (string) -- ISO-3166-1 language code
373
374                     Returns
375                            the corresponding custom code
376
377                     Return type
378                            string
379
380                     Raise  CountryConvertError
381
382       class babelfish.converters.CountryReverseConverter
383              A  CountryConverter  able to reverse a custom code into a alpha2
384              ISO-3166-1 country code
385
386              reverse(code)
387                     Reverse a custom code into alpha2 code
388
389                     Parameters
390                            code (string) -- custom code to reverse
391
392                     Returns
393                            the corresponding alpha2 ISO-3166-1 country code
394
395                     Return type
396                            string
397
398                     Raise  CountryReverseError
399
400       class babelfish.converters.ConverterManager
401              Manager for babelfish converters behaving like a dict with  lazy
402              loading
403
404              Loading is done in this order:
405
406              • Entry point converters
407
408              • Registered converters
409
410              • Internal converters
411
412              entry_point
413                     The entry point where to look for converters
414
415              internal_converters
416                     Internal converters with entry point syntax
417
418              registered_converters
419                     Registered converters with entry point syntax
420
421              converters
422                     Loaded converters
423
424              register(entry_point)
425                     Register a converter
426
427                     Parameters
428                            entry_point (string) -- converter to register (en‐
429                            try point syntax)
430
431                     Raise  ValueError if already registered
432
433              unregister(entry_point)
434                     Unregister a converter
435
436                     Parameters
437                            entry_point (string) --  converter  to  unregister
438                            (entry point syntax)
439
440   Exceptions
441       class babelfish.exceptions.Error
442              Base class for all exceptions in babelfish
443
444       class  babelfish.exceptions.LanguageConvertError(alpha3,  country=None,
445       script=None)
446              Exception raised by converters when convert() fails
447
448              Parameters
449
450alpha3 (string) -- alpha3 code that failed conversion
451
452country (string or None) -- country  code  that  failed
453                       conversion, if any
454
455script (string or None) -- script code that failed con‐
456                       version, if any
457
458       class babelfish.exceptions.LanguageReverseError(code)
459              Exception raised by converters when reverse() fails
460
461              Parameters
462                     code (string) -- code that failed reverse conversion
463
464       class babelfish.exceptions.CountryConvertError(alpha2)
465              Exception raised by converters when convert() fails
466
467              Parameters
468                     alpha2 (string) -- alpha2 code that failed conversion
469
470       class babelfish.exceptions.CountryReverseError(code)
471              Exception raised by converters when reverse() fails
472
473              Parameters
474                     code (string) -- code that failed reverse conversion
475

0.5.5

477       release date: 2015-10-31
478
479       • Fix hasattr on Country object when called with an invalid attribute
480

0.5.4

482       release date: 2015-01-24
483
484       • Fix setuptools deprecation warning
485

0.5.3

487       release date: 2014-06-22
488
489       • Better equality semantics for Language, Country, Script
490

0.5.2

492       release date: 2014-05-25
493
494       • Babelfish objects (Language, Country, Script) are now picklable
495
496       • Added support for Python 3.4
497

0.5.1

499       release date: 2014-01-26
500
501       • Add a register method to ConverterManager to register without loading
502

0.5.0

504       release date: 2014-01-25
505
506       WARNING: Backward incompatible changes
507
508       • Simplify converter management with ConverterManager class
509
510       • Make babelfish usable in place
511
512       • Add Python 2.6 / 3.2 compatibility
513

0.4.0

515       release date: 2013-11-21
516
517       WARNING: Backward incompatible changes
518
519       • Add converter support for Country
520
521       • Language/country reverse name detection is now case-insensitive
522
523       • Add alpha3t, scope and type converters
524
525       • Use lazy loading of converters
526

0.3.0

528       release date: 2013-11-09
529
530       • Add support for scripts
531
532       • Improve built-in converters
533
534       • Add support for ietf
535

0.2.1

537       release date: 2013-11-03
538
539       • Fix reading of data files
540

0.2.0

542       release date: 2013-10-31
543
544       • Add str method
545
546       • More explicit exceptions
547
548       • Change repr format to use ascii only
549

0.1.5

551       release date: 2013-10-21
552
553       • Add a fromcode method on Language class
554
555       • Add a codes attribute on converters
556

0.1.4

558       release date: 2013-10-20
559
560       • Fix converters not raising NoConversionError
561

0.1.3

563       release date: 2013-09-29
564
565       • Fix source distribution
566

0.1.2

568       release date: 2013-09-29
569
570       • Add missing files to source distribution
571

0.1.1

573       release date: 2013-09-28
574
575       • Fix python3 support
576

0.1

578       release date: 2013-09-28
579
580       • Initial version
581

AUTHOR

583       Antoine Bertin
584
586       2021 the BabelFish authors
587
588
589
590
5910.5.5-dev                        Jan 27, 2021                     BABELFISH(1)
Impressum