bencode-py

library4.0.0pypypi✓ verified 85d ago

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.

serialization

pip install bencode-py

github ↗package ↗

INSTALL

IMPORT

SIG · BENCODE-PY

bencode-py

serializationpythonv4.0.0

Install

1.5s avg

Import

23ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.025s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.021s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bencodepy

✓ import bencodepy

✗ import bencode

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.

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}')

Debug

Known issues

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

affects: 4.0.0+

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

affects: 3.0.0+

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

NameError: name 'bdecode' is not defined

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

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'

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.

Upgrade

Version history

4.0.0latest on PyPI · released Jun 12, 2020

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fuzeman/bencode.py ↗

packagehttps://pypi.org/project/bencode-py/ ↗