Bencode.py

Common errors

• NameError: name 'bdecode' is not defined

  cause The functions for encoding and decoding are methods of the `bencodepy` module (or `bencode` for legacy) directly, not standalone global functions.
  fix After `import bencodepy`, use `bencodepy.decode(data)` or `bencodepy.encode(data)`. Do not call `decode(data)` or `encode(data)` directly.

• bencodepy.exceptions.BencodeDecodeError: not a valid bencoded string

  cause The input byte string provided to `decode` does not conform to the Bencode specification, indicating corruption, truncation, or incorrect data format.
  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.

• TypeError: a bytes-like object is required, not 'str'

  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.
  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.

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: Upgrade your Python environment to Python 3.6 or newer. Python 3.8+ is recommended for optimal compatibility.
• gotcha 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.
  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`.
• gotcha 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.
  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.

Install

• pip install bencode-py Install latest version

Imports

• bencodepy
  wrong:

  import bencode

  correct:

  import bencodepy

  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.
• Bencode

  from bencodepy import Bencode

  Import the `Bencode` class to create custom encoder/decoder instances, allowing configuration of aspects like string encoding and dictionary ordering.

Quickstart

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.

import bencodepy

# Encode Python data to bencode bytes
data_to_encode = {
    'message': 'hello world',
    'number': 123,
    'list_of_items': ['item1', 2, b'binary_data']
}
bencoded_data = bencodepy.encode(data_to_encode)
print(f"Encoded: {bencoded_data}")

# Decode bencode bytes to Python data
decoded_data = bencodepy.decode(bencoded_data)
print(f"Decoded: {decoded_data}")

# Decode to UTF-8 strings by default using a custom Bencode instance
bc = bencodepy.Bencode(encoding='utf-8')
utf8_decoded = bc.decode(b'd7:message11:hello worlde')
print(f"UTF-8 Decoded: {utf8_decoded}')