__init__.py revision 988ad2bdff836665f004c285fb09182c35775fd6 
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
25Written by Marc-Andre Lemburg (mal@lemburg.com).
26
27(c) Copyright CNRI, All Rights Reserved. NO WARRANTY.
28
29"""#"
30
31import codecs,aliases
32
33_cache = {}
34_unknown = '--unknown--'
35
36def 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
86codecs.register(search_function)
87