bencode2

A fast and correct bencode serialize/deserialize library

introduction

Why yet another bencode package in python?

because I need a bencode library:

1. Correct, which mean it should fully validate its inputs, and won't try to decode bencode bytes to str by default. Bencode doesn't have a utf-8 str type, only bytes, so many decoder try to decode bytes to str and fallback to bytes, this package won't, it parse bencode bytes value as python bytes.
2. Fast enough, that's why this package is written with c++.
3. even cross implement, what's why this package sill have a pure python fallback and bencode2-${version}-py3-none-any.whl wheel on pypi.

install

pip install bencode2

basic usage

import bencode2

assert bencode2.bdecode(b"d4:spaml1:a1:bee") == {b"spam": [b"a", b"b"]}

assert bencode2.bencode({'hello': 'world'}) == b'd5:hello5:worlde'

Decoding

bencode type	python type
integer	int
string	bytes
array	list
directory	dict

bencode have 4 native types, integer, string, array and directory.

This package will decode integer to int, array to list and directory to dict.

Because bencode string is not defined as utf-8 string, and will contain raw bytes bencode2 will decode bencode string to python bytes.

Encoding

python type	bencode type
bool	integer 0/1
int, enum.IntEnum	integer
str, enum.StrEnum	string
bytes, bytearray,memoryview	string
list, tuple, NamedTuple	array
dict, OrderedDict	directory
types.MaapingProxy	directory
dataclasses	directory

free threading

bencode2 have a free threading wheel on pypi, build with GIL disabled.

When encoding or decoding, it will not acquire GIL, which mean it's the caller's responsibility to ensure thread safety.

When calling bencode, it's safe to encode same object in multiple threading, but it's not safe to encoding a object and change it in another thread at same time.

Also, when decoding, bytes objects are immutable so it's safe to be used in multiple threading, but memoryview and bytearray maybe not, please make sure underlay data doesn't change when decoding.