API Reference

webencodings.lookup(label)

Look for an encoding by its label.

This is the spec’s get an encoding algorithm. Supported labels are listed there.

Parameters:

label – A string.

Returns:

An Encoding object, or None for an unknown label.

class webencodings.Encoding

A character encoding that can be used for decoding or encoding.

name

Canonical name of the encoding

codec_info

The actual implementation of the encoding, a stdlib CodecInfo object. See codecs.register().

webencodings.UTF8 = <Encoding utf-8>

The UTF-8 encoding. Should be used for new content and formats.

webencodings.decode(input, fallback_encoding, errors='replace')

Decode a single string.

Parameters:

• input – A byte string

• fallback_encoding – An Encoding object or a label string. The encoding to use if input does not have a BOM.

• errors – Type of error handling. See codecs.register().

Raises:

LookupError for an unknown encoding label.

Returns:

A (output, encoding) tuple of an Unicode string and an Encoding.

webencodings.encode(input, encoding=<Encoding utf-8>, errors='strict')

Encode a single string.

Parameters:

• input – An Unicode string.

• encoding – An Encoding object or a label string.

• errors – Type of error handling. See codecs.register().

Raises:

LookupError for an unknown encoding label.

Returns:

A byte string.

webencodings.iter_decode(input, fallback_encoding, errors='replace')

“Pull”-based decoder.

Parameters:

• input –

  An iterable of byte strings.

  The input is first consumed just enough to determine the encoding based on the precense of a BOM, then consumed on demand when the return value is.

• fallback_encoding – An Encoding object or a label string. The encoding to use if input does not have a BOM.

• errors – Type of error handling. See codecs.register().

Raises:

LookupError for an unknown encoding label.

Returns:

An (output, encoding) tuple. output is an iterable of Unicode strings, encoding is the Encoding that is being used.

webencodings.iter_encode(input, encoding=<Encoding utf-8>, errors='strict')

“Pull”-based encoder.

Parameters:

• input – An iterable of Unicode strings.

• encoding – An Encoding object or a label string.

• errors – Type of error handling. See codecs.register().

Raises:

LookupError for an unknown encoding label.

Returns:

An iterable of byte strings.

class webencodings.IncrementalDecoder(fallback_encoding, errors='replace')

“Push”-based decoder.

Parameters:

• fallback_encoding – An Encoding object or a label string. The encoding to use if input does not have a BOM.

• errors – Type of error handling. See codecs.register().

Raises:

LookupError for an unknown encoding label.

decode(input, final=False)

Decode one chunk of the input.

Parameters:

• input – A byte string.

• final – Indicate that no more input is available. Must be True if this is the last call.

Returns:

An Unicode string.

encoding

The actual Encoding that is being used, or None if that is not determined yet. (Ie. if there is not enough input yet to determine if there is a BOM.)

class webencodings.IncrementalEncoder(encoding=<Encoding utf-8>, errors='strict')

“Push”-based encoder.

Parameters:

• encoding – An Encoding object or a label string.

• errors – Type of error handling. See codecs.register().

Raises:

LookupError for an unknown encoding label.

encode(input, final=False)

Parameters:

• input – An Unicode string.

• final – Indicate that no more input is available. Must be True if this is the last call.

Returns:

A byte string.

webencodings.ascii_lower(string)

Transform (only) ASCII letters to lower case: A-Z is mapped to a-z.

Parameters:

string – An Unicode string.

Returns:

A new Unicode string.

This is used for ASCII case-insensitive matching of encoding labels. The same matching is also used, among other things, for CSS keywords.

This is different from the str.lower() method of Unicode strings which also affect non-ASCII characters, sometimes mapping them into the ASCII range:

>>> keyword = 'Bac\N{KELVIN SIGN}ground'
>>> assert keyword.lower() == 'background'
>>> assert ascii_lower(keyword) != keyword.lower()
>>> assert ascii_lower(keyword) == 'bac\N{KELVIN SIGN}ground'