{"id":729,"library":"webencodings","title":"Web Encodings","description":"webencodings is a Python library that implements the WHATWG Encoding Standard. It provides character encoding aliases and rules for handling legacy web content, such as US-ASCII and ISO-8859-1 mapping to Windows-1252, and byte order mark (BOM) detection. The current version is 0.5.1, and its release cadence is considered stalled.","status":"maintenance","version":"0.5.1","language":"python","source_language":"en","source_url":"https://github.com/SimonSapin/python-webencodings","tags":["web","encoding","unicode","WHATWG","charset","BOM"],"install":[{"cmd":"pip install webencodings","lang":"bash","label":"Latest stable version"}],"dependencies":[],"imports":[{"note":"Used to find an encoding by its label according to the WHATWG standard.","symbol":"lookup","correct":"from webencodings import lookup"},{"note":"While `decode` and `encode` functions exist, they are often used via the `Encoding` object returned by `lookup` or directly if importing `sync`.","symbol":"decode","correct":"from webencodings.sync import decode"},{"note":"While `decode` and `encode` functions exist, they are often used via the `Encoding` object returned by `lookup` or directly if importing `sync`.","symbol":"encode","correct":"from webencodings.sync import encode"}],"quickstart":{"code":"from webencodings import lookup\n\n# Look up an encoding by its label\nutf8_encoding = lookup('utf-8')\n\nif utf8_encoding:\n    # Encode a string\n    text_to_encode = \"Hello, world!\"\n    encoded_bytes = utf8_encoding.encode(text_to_encode)\n    print(f\"Encoded bytes: {encoded_bytes}\")\n\n    # Decode bytes (with default error handling 'replace')\n    bytes_to_decode = b'Hello, world!\\xed'\n    decoded_text = utf8_encoding.decode(bytes_to_decode)\n    print(f\"Decoded text (with replace): {decoded_text}\")\n\n    # Decode bytes with strict error handling\n    try:\n        decoded_text_strict = utf8_encoding.decode(bytes_to_decode, errors='strict')\n        print(f\"Decoded text (strict): {decoded_text_strict}\")\n    except UnicodeDecodeError as e:\n        print(f\"Strict decoding error: {e}\")\nelse:\n    print(\"UTF-8 encoding not found.\")","lang":"python","description":"This quickstart demonstrates how to use `webencodings.lookup` to retrieve an `Encoding` object, and then use its `encode` and `decode` methods. It also highlights the default 'replace' error handling for decoding and how to explicitly use 'strict' handling."},"warnings":[{"fix":"If strict error handling is desired, explicitly pass `errors='strict'` to the `decode` method: `encoding.decode(bytes_data, errors='strict')`.","message":"The default error handling for `webencodings` decoding is 'replace', which replaces invalid bytes with the replacement character (U+FFFD). This differs from Python's standard library `codecs` module, which defaults to 'strict' and raises a `UnicodeDecodeError`.","severity":"gotcha","affected_versions":"0.5.1 and earlier"},{"fix":"Access the underlying `codecs.CodecInfo` object via the `codec_info` attribute of the `Encoding` object, or the encoding name string via `python_encoding`, and use its `encode` or `decode` methods. For example, instead of `encoding_obj.encode(...)`, use `encoding_obj.codec_info.encode(...)` or `encoding_obj.python_encoding.encode(...)`.","message":"The `webencodings.get_encoding()` method returns an `Encoding` object, which serves as a detection and mapping layer. The actual encoding and decoding operations are performed by Python's standard `codecs` module, which this `Encoding` object wraps. Consequently, the `Encoding` object itself does not expose `encode` or `decode` methods directly, leading to an `AttributeError` if attempted.","severity":"gotcha","affected_versions":"0.5.1 and earlier"},{"fix":"Monitor for actively maintained alternatives if long-term support and up-to-date standards compliance are critical for new projects. For existing projects, be aware of potential compatibility issues with newer Python versions, though it currently supports Python 2.6+ and 3.3+.","message":"The library's development status on PyPI is '4 - Beta' and its release cadence is 'Stalled', with the last release in April 2017. While widely used, it indicates a lack of active development and may not receive updates for new encoding standards or Python versions.","severity":"deprecated","affected_versions":"0.5.1 and earlier"},{"fix":"To encode text, use the `codec` attribute of the `Encoding` object: `encoded_bytes = encoding_obj.codec.encode(text_to_encode)`. For example, if you have `utf8_encoding = webencodings.lookup('utf-8')`, use `utf8_encoding.codec.encode(text_to_encode)`.","message":"The `webencodings.Encoding` object provides a `decode` method directly, but it does not have an `encode` method. Attempting to call `encode()` on the `Encoding` object itself will result in an `AttributeError`. Encoding operations should be performed on the underlying `codecs` module object, which is accessible via the `codec` attribute of the `Encoding` instance.","severity":"gotcha","affected_versions":"0.5.1 and earlier"}],"env_vars":null,"last_verified":"2026-05-12T18:20:44.249Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install webencodings","cause":"The 'webencodings' package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'webencodings'"},{"fix":"from webencodings import decode; decoded_text = decode('utf-8', b'some bytes')","cause":"The `webencodings.decode` function requires both an encoding name (first argument) and the byte string to be decoded (second argument).","error":"TypeError: webencodings.decode() missing 1 required positional argument: 'byte_string'"},{"fix":"from webencodings import lookup; encoding_obj = lookup(b'utf-8')","cause":"The `lookup` function was called without being properly imported from the `webencodings` library or without qualifying it with `webencodings.`.","error":"NameError: name 'lookup' is not defined"},{"fix":"from webencodings import lookup; encoding_obj = lookup(b'utf-8'); if encoding_obj: decoded = encoding_obj.decode(b'hello') else: print('Invalid encoding specified')","cause":"`webencodings.lookup()` returned `None` because the specified encoding name was invalid or unrecognized, and a subsequent call to `.decode()` was attempted on this `None` object.","error":"AttributeError: 'NoneType' object has no attribute 'decode'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.5.1","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"17.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"17.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0,"mem_mb":0.1,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.1,"disk_size":"19.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.1,"disk_size":"19.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0,"mem_mb":0.1,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.2,"disk_size":"11.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"11.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0,"mem_mb":0.2,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.2,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"11.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"11.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"17.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"17.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.02,"mem_mb":0.1,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}