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 normalized encoding

     7     names as defined in the normalize_encoding() function below, e.g.

     8     'utf-8' must be implemented by the module 'utf_8.py'.

     9 

    10     Each codec module must export the following interface:

    11 

    12     * getregentry() -> codecs.CodecInfo object

    13     The getregentry() API must a CodecInfo object with encoder, decoder,

    14     incrementalencoder, incrementaldecoder, streamwriter and streamreader

    15     atttributes which adhere to the Python Codec Interface Standard.

    16 

    17     In addition, a module may optionally also define the following

    18     APIs which are then used by the package's codec search function:

    19 

    20     * getaliases() -> sequence of encoding name strings to use as aliases

    21 

    22     Alias names returned by getaliases() must be normalized encoding

    23     names as defined by normalize_encoding().

    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

    32 from encodings import aliases

    33 import __builtin__

    34 

    35 _cache = {}

    36 _unknown = '--unknown--'

    37 _import_tail = ['*']

    38 _norm_encoding_map = ('                                              . '

    39                       '0123456789       ABCDEFGHIJKLMNOPQRSTUVWXYZ     '

    40                       ' abcdefghijklmnopqrstuvwxyz                     '

    41                       '                                                '

    42                       '                                                '

    43                       '                ')

    44 _aliases = aliases.aliases

    45 

    46 class CodecRegistryError(LookupError, SystemError):

    47     pass

    48 

    49 def normalize_encoding(encoding):

    50 

    51     """ Normalize an encoding name.

    52 

    53         Normalization works as follows: all non-alphanumeric

    54         characters except the dot used for Python package names are

    55         collapsed and replaced with a single underscore, e.g. '  -;#'

    56         becomes '_'. Leading and trailing underscores are removed.

    57 

    58         Note that encoding names should be ASCII only; if they do use

    59         non-ASCII characters, these must be Latin-1 compatible.

    60 

    61     """

    62     # Make sure we have an 8-bit string, because .translate() works

    63     # differently for Unicode strings.

    64     if hasattr(__builtin__, "unicode") and isinstance(encoding, unicode):

    65         # Note that .encode('latin-1') does *not* use the codec

    66         # registry, so this call doesn't recurse. (See unicodeobject.c

    67         # PyUnicode_AsEncodedString() for details)

    68         encoding = encoding.encode('latin-1')

    69     return '_'.join(encoding.translate(_norm_encoding_map).split())

    70 

    71 def search_function(encoding):

    72 

    73     # Cache lookup

    74     entry = _cache.get(encoding, _unknown)

    75     if entry is not _unknown:

    76         return entry

    77 

    78     # Import the module:

    79     #

    80     # First try to find an alias for the normalized encoding

    81     # name and lookup the module using the aliased name, then try to

    82     # lookup the module using the standard import scheme, i.e. first

    83     # try in the encodings package, then at top-level.

    84     #

    85     norm_encoding = normalize_encoding(encoding)

    86     aliased_encoding = _aliases.get(norm_encoding) or \

    87                        _aliases.get(norm_encoding.replace('.', '_'))

    88     if aliased_encoding is not None:

    89         modnames = [aliased_encoding,

    90                     norm_encoding]

    91     else:

    92         modnames = [norm_encoding]

    93     for modname in modnames:

    94         if not modname or '.' in modname:

    95             continue

    96         try:

    97             # Import is absolute to prevent the possibly malicious import of a

    98             # module with side-effects that is not in the 'encodings' package.

    99             mod = __import__('encodings.' + modname, fromlist=_import_tail,

   100                              level=0)

   101         except ImportError:

   102             pass

   103         else:

   104             break

   105     else:

   106         mod = None

   107 

   108     try:

   109         getregentry = mod.getregentry

   110     except AttributeError:

   111         # Not a codec module

   112         mod = None

   113 

   114     if mod is None:

   115         # Cache misses

   116         _cache[encoding] = None

   117         return None

   118 

   119     # Now ask the module for the registry entry

   120     entry = getregentry()

   121     if not isinstance(entry, codecs.CodecInfo):

   122         if not 4 <= len(entry) <= 7:

   123             raise CodecRegistryError,\

   124                  'module "%s" (%s) failed to register' % \

   125                   (mod.__name__, mod.__file__)

   126         if not callable(entry[0]) or \

   127            not callable(entry[1]) or \

   128            (entry[2] is not None and not callable(entry[2])) or \

   129            (entry[3] is not None and not callable(entry[3])) or \

   130            (len(entry) > 4 and entry[4] is not None and not callable(entry[4])) or \

   131            (len(entry) > 5 and entry[5] is not None and not callable(entry[5])):

   132             raise CodecRegistryError,\

   133                 'incompatible codecs in module "%s" (%s)' % \

   134                 (mod.__name__, mod.__file__)

   135         if len(entry)<7 or entry[6] is None:

   136             entry += (None,)*(6-len(entry)) + (mod.__name__.split(".", 1)[1],)

   137         entry = codecs.CodecInfo(*entry)

   138 

   139     # Cache the codec registry entry

   140     _cache[encoding] = entry

   141 

   142     # Register its aliases (without overwriting previously registered

   143     # aliases)

   144     try:

   145         codecaliases = mod.getaliases()

   146     except AttributeError:

   147         pass

   148     else:

   149         for alias in codecaliases:

   150             if not _aliases.has_key(alias):

   151                 _aliases[alias] = modname

   152 

   153     # Return the registry entry

   154     return entry

   155 

   156 # Register the search_function in the Python codec registry

   157 codecs.register(search_function)