{"id":8878,"library":"bencode-py","title":"Bencode.py","description":"Bencode.py is a simple bencode parser for Python, compatible with Python 2, Python 3, and PyPy. Version 4.0.0 is the current stable release, which refactored the API into a new module, `bencodepy`. The library provides an intuitive API for encoding and decoding Bencode data, a serialization format primarily used in BitTorrent, and maintains an active release cadence.","status":"active","version":"4.0.0","language":"en","source_language":"en","source_url":"https://github.com/fuzeman/bencode.py","tags":["bencode","bittorrent","parser","encoding","decoding","serialization"],"install":[{"cmd":"pip install bencode-py","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"As of v4.0.0, the recommended and improved API is primarily exposed via the `bencodepy` module. The `bencode` module is retained for backward compatibility but is essentially a proxy to `bencodepy` with specific default settings, and direct use of `bencodepy` is advised for new code for more reliable and explicit control.","wrong":"import bencode","symbol":"bencodepy","correct":"import bencodepy"},{"note":"Import the `Bencode` class to create custom encoder/decoder instances, allowing configuration of aspects like string encoding and dictionary ordering.","symbol":"Bencode","correct":"from bencodepy import Bencode"}],"quickstart":{"code":"import bencodepy\n\n# Encode Python data to bencode bytes\ndata_to_encode = {\n    'message': 'hello world',\n    'number': 123,\n    'list_of_items': ['item1', 2, b'binary_data']\n}\nbencoded_data = bencodepy.encode(data_to_encode)\nprint(f\"Encoded: {bencoded_data}\")\n\n# Decode bencode bytes to Python data\ndecoded_data = bencodepy.decode(bencoded_data)\nprint(f\"Decoded: {decoded_data}\")\n\n# Decode to UTF-8 strings by default using a custom Bencode instance\nbc = bencodepy.Bencode(encoding='utf-8')\nutf8_decoded = bc.decode(b'd7:message11:hello worlde')\nprint(f\"UTF-8 Decoded: {utf8_decoded}')","lang":"python","description":"This quickstart demonstrates how to encode Python dictionaries, integers, and lists into bencode format, and then decode bencoded bytes back into Python data structures. It also shows how to configure `bencodepy` to decode strings as UTF-8 rather than raw bytes."},"warnings":[{"fix":"Update `import bencode` statements to `import bencodepy`. For existing code relying on specific `bencode` module behavior, consider migrating to `bencodepy.Bencode` instances for explicit control.","message":"Version 4.0.0 introduces a significant API change. The primary, improved API for encoding and decoding has moved from `bencode` to a new top-level module named `bencodepy`. While `import bencode` still works for backward compatibility, it's recommended to update imports to `import bencodepy` and use its functions directly.","severity":"breaking","affected_versions":"4.0.0+"},{"fix":"Upgrade your Python environment to Python 3.6 or newer. Python 3.8+ is recommended for optimal compatibility.","message":"Version 3.0.0 dropped official support for Python 2.6 and Python 3.4. Code running on these Python versions will not be supported and may encounter issues.","severity":"breaking","affected_versions":"3.0.0+"},{"fix":"When decoding, if `str` objects are desired, create a `Bencode` instance: `bc = bencodepy.Bencode(encoding='utf-8')` and use `bc.decode(bencoded_data)`. Remember to encode Python `str` to `bytes` (e.g., `s.encode('utf-8')`) before passing them to `bencodepy.encode`.","message":"Bencode strings are inherently byte sequences, not Unicode strings. By default, `bencodepy.decode` will return byte strings (`bytes`). If you expect Python `str` objects, you must explicitly specify an `encoding` (e.g., 'utf-8') when creating a `Bencode` instance for decoding.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If dictionary key order is critical, initialize `Bencode` with `dict_ordered=True`: `bc = bencodepy.Bencode(dict_ordered=True)`. This will cause decoded dictionaries to be `OrderedDict` instances. For advanced sorting, `dict_ordered_sort=True` can also be used.","message":"Bencode dictionaries do not guarantee key order. While `bencodepy` can decode to a standard Python `dict`, certain applications (e.g., BitTorrent info hash calculations) require `OrderedDict` to preserve key order.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"After `import bencodepy`, use `bencodepy.decode(data)` or `bencodepy.encode(data)`. Do not call `decode(data)` or `encode(data)` directly.","cause":"The functions for encoding and decoding are methods of the `bencodepy` module (or `bencode` for legacy) directly, not standalone global functions.","error":"NameError: name 'bdecode' is not defined"},{"fix":"Verify the integrity and source of the bencoded string. Ensure it is complete and properly formatted Bencode. Debug by attempting to decode a known-good bencoded string to isolate the issue.","cause":"The input byte string provided to `decode` does not conform to the Bencode specification, indicating corruption, truncation, or incorrect data format.","error":"bencodepy.exceptions.BencodeDecodeError: not a valid bencoded string"},{"fix":"Before encoding, ensure all string values in your Python data are converted to `bytes` (e.g., `my_string.encode('utf-8')`). When decoding, if you require `str` objects, initialize `bencodepy.Bencode(encoding='utf-8')` to perform automatic decoding.","cause":"Python 3 distinguishes between `str` (Unicode) and `bytes`. Bencode operations require `bytes` objects for both input and output (unless an explicit `encoding` is set for decoding). Passing a `str` directly without encoding it will raise this error.","error":"TypeError: a bytes-like object is required, not 'str'"}]}