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

0.5.5

479       release date: 2015-10-31
480
481       · Fix hasattr on Country object when called with an invalid attribute
482

0.5.4

484       release date: 2015-01-24
485
486       · Fix setuptools deprecation warning
487

0.5.3

489       release date: 2014-06-22
490
491       · Better equality semantics for Language, Country, Script
492

0.5.2

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

0.5.1

501       release date: 2014-01-26
502
503       · Add a register method to ConverterManager to register without loading
504

0.5.0

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

0.4.0

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

0.3.0

530       release date: 2013-11-09
531
532       · Add support for scripts
533
534       · Improve built-in converters
535
536       · Add support for ietf
537

0.2.1

539       release date: 2013-11-03
540
541       · Fix reading of data files
542

0.2.0

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

0.1.5

553       release date: 2013-10-21
554
555       · Add a fromcode method on Language class
556
557       · Add a codes attribute on converters
558

0.1.4

560       release date: 2013-10-20
561
562       · Fix converters not raising NoConversionError
563

0.1.3

565       release date: 2013-09-29
566
567       · Fix source distribution
568

0.1.2

570       release date: 2013-09-29
571
572       · Add missing files to source distribution
573

0.1.1

575       release date: 2013-09-28
576
577       · Fix python3 support
578

0.1

580       release date: 2013-09-28
581
582       · Initial version
583

AUTHOR

585       Antoine Bertin
586
588       2020 the BabelFish authors
589
590
591
592
5930.5.5-dev                        Jan 30, 2020                     BABELFISH(1)
Impressum