Lib/encodings/__init__.py

   1 """ Standard "encodings" Package
   2
   3     Standard Python encoding modules are stored in this package
   4     directory.
   5
   6     Codec modules must have names corresponding to standard lower-case
   7     encoding names with hyphens mapped to underscores, e.g. 'utf-8' is
   8     implemented by the module 'utf_8.py'.
   9
  10     Each codec module must export the following interface:
  11
  12     * getregentry() -> (encoder, decoder, stream_reader, stream_writer)
  13     The getregentry() API must return callable objects which adhere to
  14     the Python Codec Interface Standard.
  15
  16     In addition, a module may optionally also define the following
  17     APIs which are then used by the package's codec search function:
  18
  19     * getaliases() -> sequence of encoding name strings to use as aliases
  20
  21     Alias names returned by getaliases() must be standard encoding
  22     names as defined above (lower-case, hyphens converted to
  23     underscores).
  24
  25 Written by Marc-Andre Lemburg (mal@lemburg.com).
  26
  27 (c) Copyright CNRI, All Rights Reserved. NO WARRANTY.
  28
  29 """#"
  30
  31 import codecs,aliases
  32
  33 _cache = {}
  34 _unknown = '--unknown--'
  35
  36 def search_function(encoding):
  37
  38     # Cache lookup
  39     entry = _cache.get(encoding,_unknown)
  40     if entry is not _unknown:
  41         return entry
  42
  43     # Import the module
  44     modname = encoding.replace('-', '_')
  45     modname = aliases.aliases.get(modname,modname)
  46     try:
  47         mod = __import__(modname,globals(),locals(),'*')
  48     except ImportError,why:
  49         # cache misses
  50         _cache[encoding] = None
  51         return None
  52
  53     # Now ask the module for the registry entry
  54     try:
  55         entry = tuple(mod.getregentry())
  56     except AttributeError:
  57         entry = ()
  58     if len(entry) != 4:
  59         raise SystemError,\
  60               'module "%s.%s" failed to register' % \
  61               (__name__,modname)
  62     for obj in entry:
  63         if not callable(obj):
  64             raise SystemError,\
  65                   'incompatible codecs in module "%s.%s"' % \
  66                   (__name__,modname)
  67
  68     # Cache the codec registry entry
  69     _cache[encoding] = entry
  70
  71     # Register its aliases (without overwriting previously registered
  72     # aliases)
  73     try:
  74         codecaliases = mod.getaliases()
  75     except AttributeError:
  76         pass
  77     else:
  78         for alias in codecaliases:
  79             if not aliases.aliases.has_key(alias):
  80                 aliases.aliases[alias] = modname
  81
  82     # Return the registry entry
  83     return entry
  84
  85 # Register the search_function in the Python codec registry
  86 codecs.register(search_function)