bencode2 0.3.27__cp313-cp313-win_arm64.whl

bencode2/__decoder.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+from typing import Any, Final
+
+from typing_extensions import Buffer
+
+char_l: Final = ord("l")
+char_i: Final = ord("i")
+char_e: Final = ord("e")
+char_d: Final = ord("d")
+char_0: Final = ord("0")
+char_9: Final = ord("9")
+char_dash: Final = ord("-")
+char_colon: Final = ord(":")
+
+
+class BencodeDecodeError(ValueError):
+    """Bencode decode error."""
+
+
+def bdecode(value: Buffer, /) -> Any:
+    """Decode bencode formatted bytes to python value."""
+    return Decoder(memoryview(value).cast("B")).decode()
+
+
+class Decoder:
+    value: memoryview
+    index: int
+    size: int
+
+    __slots__ = ("value", "index", "size")
+
+    def __init__(self, value: memoryview) -> None:
+        self.size = len(value)
+        if self.size == 0:
+            raise BencodeDecodeError("empty input")
+
+        self.value = value
+        self.index = 0
+
+    def decode(self) -> object:
+        data = self.__decode()
+
+        if self.index != self.size:  # pragma: no cover
+            raise BencodeDecodeError("invalid bencode value (data after valid prefix)")
+
+        return data
+
+    def __decode(self) -> object:
+        if char_0 <= self.value[self.index] <= char_9:
+            return self.__decode_bytes()
+        if self.value[self.index] == char_i:
+            return self.__decode_int()
+        if self.value[self.index] == char_d:
+            return self.__decode_dict()
+        if self.value[self.index] == char_l:
+            return self.__decode_list()
+
+        raise BencodeDecodeError(
+            f"unexpected token {self.value[self.index:self.index + 1].tobytes()}. "
+            f"index {self.index}"
+        )
+
+    def __decode_int(self) -> int:
+        self.index += 1
+        for i, c in enumerate(self.value[self.index :]):
+            if c == char_e:
+                index_end = i + self.index
+                break
+        else:
+            raise BencodeDecodeError(
+                f"invalid int, failed to found end. index {self.index}"
+            )
+
+        if index_end == self.index:
+            raise BencodeDecodeError(f"invalid int, found 'ie': {self.index}")
+
+        n: int = 1
+        offset: int = 0
+
+        if self.value[self.index] == char_dash:
+            n = -1
+            offset = 1
+
+        total: int = 0
+        for c in self.value[self.index + offset : index_end]:
+            if not (char_0 <= c <= char_9):
+                raise BencodeDecodeError(
+                    f"malformed int {self.value[self.index:index_end].tobytes()}. index {self.index}"
+                )
+            total = total * 10 + (c - char_0)
+
+        n = total * n
+
+        if self.value[self.index] == char_dash:
+            if self.value[self.index + 1] == char_0:
+                raise BencodeDecodeError(
+                    f"-0 is not allowed in bencoding. index: {self.index}"
+                )
+        elif self.value[self.index] == char_0 and index_end != self.index + 1:
+            raise BencodeDecodeError(
+                f"integer with leading zero is not allowed. index: {self.index}"
+            )
+        self.index = index_end + 1
+        return n
+
+    def __decode_list(self) -> list[Any]:
+        r: list[Any] = []
+        self.index += 1
+
+        while True:
+            if self.index >= self.size:
+                raise BencodeDecodeError(
+                    f"buffer overflow when decoding array, index {self.index}"
+                )
+
+            if self.value[self.index] == char_e:
+                break
+
+            v = self.__decode()
+            r.append(v)
+
+        self.index += 1
+        return r
+
+    def __decode_bytes(self) -> bytes:
+        for i, c in enumerate(self.value[self.index :]):
+            if c == char_colon:
+                index_colon = i + self.index
+                break
+        else:
+            raise BencodeDecodeError(
+                f"invalid bytes, failed find expected char ':'. index {self.index}"
+            )
+
+        if self.value[self.index] == char_0:
+            if index_colon != self.index + 1:
+                raise BencodeDecodeError(
+                    f"malformed str/bytes length with leading 0. index {self.index}"
+                )
+
+        n: int = 0
+        for c in self.value[self.index : index_colon]:
+            if not (char_0 <= c <= char_9):
+                raise BencodeDecodeError(
+                    f"malformed str/bytes length {self.value[self.index:index_colon].tobytes()!r}."
+                    f" index {self.index}"
+                )
+
+            n = n * 10 + (c - char_0)
+
+        if index_colon + n >= self.size:
+            raise BencodeDecodeError(
+                f"malformed str/bytes length, buffer overflow. index {self.index}"
+            )
+
+        index_colon += 1
+
+        s = self.value[index_colon : index_colon + n]
+
+        self.index = index_colon + n
+
+        return s.tobytes()
+
+    def __decode_dict(self) -> dict[str | bytes, Any]:
+        start_index = self.index
+        self.index += 1
+
+        items: list[tuple[bytes, Any]] = []
+
+        while True:
+            if self.index >= self.size:
+                raise BencodeDecodeError(
+                    f"buffer overflow when decoding bytes, index {self.index}"
+                )
+            if self.value[self.index] == char_e:
+                break
+            if not (char_0 <= self.value[self.index] <= char_9):
+                raise BencodeDecodeError(
+                    f"directory only allow str as keys, "
+                    f"found unexpected char "
+                    f"'{self.value[self.index]:c}', index {self.index}"
+                )
+            k = self.__decode_bytes()
+            v = self.__decode()
+            items.append((k, v))
+
+        if not items:
+            self.index += 1
+            return {}
+
+        _check_sorted(items, start_index)
+
+        self.index += 1
+
+        return dict(items)
+
+
+def _check_sorted(s: list[tuple[bytes, Any]], idx: int) -> None:
+    i = 1
+    while i < len(s):
+        if s[i][0] < s[i - 1][0]:
+            raise BencodeDecodeError(f"directory keys is not sorted, index {idx}")
+        if s[i][0] == s[i - 1][0]:
+            raise BencodeDecodeError(f"found duplicated keys in directory, index {idx}")
+        i += 1

bencode2/__encoder.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import io
+from collections import OrderedDict
+from collections.abc import Mapping
+from dataclasses import fields, is_dataclass
+from types import MappingProxyType
+from typing import Any
+
+
+class BencodeEncodeError(ValueError):
+    """Bencode encode error."""
+
+
+def bencode(value: Any, /) -> bytes:
+    """Encode value into the bencode format."""
+    with io.BytesIO() as w:
+        __encode(w, value, set(), stack_depth=0)
+        return w.getvalue()
+
+
+def __encode(w: io.BytesIO, value: Any, seen: set[int], stack_depth: int) -> None:
+    if isinstance(value, str):
+        return __encode_bytes(w, value.encode("UTF-8"))
+
+    if isinstance(value, int):
+        w.write(b"i")
+        # will handle bool and enum.IntEnum
+        w.write(str(int(value)).encode())
+        w.write(b"e")
+        return
+
+    if isinstance(value, bytes):
+        return __encode_bytes(w, value)
+
+    stack_depth += 1
+
+    i = id(value)
+    if isinstance(value, (dict, OrderedDict, MappingProxyType)):
+        if stack_depth >= 100:
+            if i in seen:
+                raise BencodeEncodeError(f"circular reference found {value!r}")
+            seen.add(i)
+        __encode_mapping(w, value, seen, stack_depth=stack_depth)
+        if stack_depth >= 100:  # pragma: no cover
+            seen.remove(i)
+        stack_depth -= 1
+        return
+
+    if isinstance(value, (list, tuple)):
+        if stack_depth >= 100:
+            if i in seen:
+                raise BencodeEncodeError(f"circular reference found {value!r}")
+            seen.add(i)
+
+        w.write(b"l")
+        for item in value:
+            __encode(w, item, seen, stack_depth=stack_depth)
+        w.write(b"e")
+
+        if stack_depth >= 100:  # pragma: no cover
+            seen.remove(i)
+        stack_depth -= 1
+
+        return
+
+    if isinstance(value, bytearray):
+        __encode_bytes(w, bytes(value))
+        return
+
+    if isinstance(value, memoryview):
+        w.write(str(len(value)).encode())
+        w.write(b":")
+        w.write(value)
+        return
+
+    if is_dataclass(value) and not isinstance(value, type):
+        if stack_depth >= 100:
+            if i in seen:
+                raise BencodeEncodeError(f"circular reference found {value!r}")
+            seen.add(i)
+
+        __encode_dataclass(w, value, seen, stack_depth=stack_depth)
+
+        if stack_depth >= 100:  # pragma: no cover
+            seen.remove(i)
+        stack_depth -= 1
+
+        return
+
+    raise TypeError(f"type '{type(value)!r}' not supported by bencode")
+
+
+def __encode_bytes(w: io.BytesIO, val: bytes) -> None:
+    w.write(str(len(val)).encode())
+    w.write(b":")
+    w.write(val)
+
+
+def __encode_mapping(
+    w: io.BytesIO,
+    val: Mapping[Any, Any],
+    seen: set[int],
+    stack_depth: int,
+) -> None:
+    w.write(b"d")
+
+    # force all keys to bytes, because str and bytes are incomparable
+    i_list: list[tuple[bytes, object]] = [(to_binary(k), v) for k, v in val.items()]
+    if not i_list:
+        w.write(b"e")
+        return
+    i_list.sort(key=lambda kv: kv[0])
+    __check_duplicated_keys(i_list)
+
+    for k, v in i_list:
+        __encode_bytes(w, k)
+        __encode(w, v, seen, stack_depth=stack_depth)
+
+    w.write(b"e")
+
+
+def __encode_dataclass(w: io.BytesIO, x: Any, seen: set[int], stack_depth: int) -> None:
+    keys = fields(x)
+    if not keys:
+        w.write(b"de")
+        return
+
+    w.write(b"d")
+
+    ks = sorted([k.name for k in keys])
+
+    # no need to check duplicated keys, dataclasses will check this.
+
+    for k in ks:
+        __encode_bytes(w, k.encode())
+        __encode(w, getattr(x, k), seen, stack_depth=stack_depth)
+
+    w.write(b"e")
+
+
+def __check_duplicated_keys(s: list[tuple[bytes, object]]) -> None:
+    last_key: bytes = s[0][0]
+    for current, _ in s[1:]:
+        if last_key == current:
+            raise BencodeEncodeError(
+                f"find duplicated keys {last_key!r} and {current.decode()}"
+            )
+        last_key = current
+
+
+def to_binary(s: str | bytes) -> bytes:
+    if isinstance(s, bytes):
+        return s
+
+    if isinstance(s, str):
+        return s.encode("utf-8", "strict")
+
+    raise TypeError(f"expected binary or text (found {type(s)})")

bencode2/__init__.py

@@ -0,0 +1,17 @@
+try:
+    from .__bencode import BencodeDecodeError, BencodeEncodeError, bdecode, bencode
+
+    COMPILED = True
+except ModuleNotFoundError:
+    from .__decoder import BencodeDecodeError, bdecode
+    from .__encoder import BencodeEncodeError, bencode
+
+    COMPILED = False
+
+__all__ = (
+    "BencodeDecodeError",
+    "BencodeEncodeError",
+    "bencode",
+    "bdecode",
+    "COMPILED",
+)

bencode2/__init__.pyi

@@ -0,0 +1,8 @@
+from .__bencode import bdecode, bencode
+
+__all__ = ["bencode", "bdecode", "BencodeDecodeError", "BencodeEncodeError", "COMPILED"]
+
+class BencodeDecodeError(ValueError): ...
+class BencodeEncodeError(ValueError): ...
+
+COMPILED: bool = ...

bencode2-0.3.27.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.1
+Name: bencode2
+Version: 0.3.27
+Summary: A fast and correct bencode serialize/deserialize library
+Keywords: bencode,bittorrent,bit-torrent,serialize,deserialize,p2p
+Author-Email: trim21 <trim21me@gmail.com>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Project-URL: Homepage, https://github.com/trim21/bencode-py
+Project-URL: Repository, https://github.com/trim21/bencode-py
+Project-URL: Issues, https://github.com/trim21/bencode-py/issues
+Requires-Python: <4.0,>=3.9
+Requires-Dist: typing_extensions>=4.8.0
+Description-Content-Type: text/markdown
+
+# A fast and correct bencode serialize/deserialize library
+
+[![PyPI](https://img.shields.io/pypi/v/bencode2)](https://pypi.org/project/bencode2/)
+[![tests](https://github.com/trim21/bencode-py/actions/workflows/tests.yaml/badge.svg)](https://github.com/trim21/bencode-py/actions/workflows/tests.yaml)
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/trim21/bencode-py/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/trim21/bencode-py/tree/master)
+[![PyPI - Python Version](https://img.shields.io/badge/python-%3E%3D3.8%2C%3C4.0-blue)](https://pypi.org/project/bencode2/)
+[![Codecov branch](https://img.shields.io/codecov/c/github/Trim21/bencode-py/master)](https://codecov.io/gh/Trim21/bencode-py/branch/master)
+
+## introduction
+
+Why yet another bencode package in python?
+
+because I need a bencode library:
+
+### 1. Correct
+
+It should fully validate its inputs, both encoded bencode bytes, or python object to be
+encoded.
+
+And it should not 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.**
+
+It may be attempting to parse all dictionary keys as string,
+but for BitTorrent v2 torrent, the keys in `pieces root` dictionary is still sha256 hash
+instead of ascii/utf-8 string.
+
+If you prefer string as dictionary keys, write a dedicated function to convert parsing
+result.
+
+Also be careful! Even file name or torrent name may not be valid utf-8 string.
+
+### 2. Fast enough
+
+this package is written with c++ in CPython.
+
+### 3. still cross implement
+
+This package sill have a pure python wheel `bencode2-${version}-py3-none-any.whl` wheel
+on pypi.
+
+Which means you can still use it in non-cpython python with same behavior.
+
+## install
+
+### pypi
+
+```shell
+pip install bencode2
+```
+
+### conda/pixi
+
+you can install conda package `bencode2` from <https://prefix.dev/channels/trim21-pkgs/packages/bencode2>.
+
+## basic usage
+
+```python
+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`    |
+|  dictionary  |   `dict`    |
+
+bencode have 4 native types, integer, string, array and dictionary.
+
+This package will decode integer to `int`, array to `list` and
+dictionary 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`       |  dictionary  |
+|       `types.MaapingProxy`        |  dictionary  |
+|            dataclasses            |  dictionary  |
+
+## free threading
+
+bencode2 have a free threading wheel on pypi, build with GIL disabled.
+
+When encoding or decoding, it will not acquire GIL and may call non-thread-safy c-api,
+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.
+
+## Development
+
+This project use [meson](https://github.com/mesonbuild/meson) for building.
+
+For testing pure python library,
+make sure all so/pyd files in `src/bencode2` are removed, then run
+`PYTHONPATH=src pytest --assert-pkg-compiled=false`.
+
+For testing native extension, meson-python doesn't provide same function with
+`python setup.py build_ext --inplace`.
+
+So you will need to run command like this:
+
+```shell
+meson setup build
+meson compile -C build
+ninja -C build copy
+```
+
+ninja will need to build so/pyd with meson and copy it to `src/bencode2`,
+
+then run tests with `PYTHONPATH=src pytest --assert-pkg-compiled=true`.

bencode2-0.3.27.dist-info/RECORD

@@ -0,0 +1,9 @@
+bencode2-0.3.27.dist-info/METADATA,sha256=i3yZybb2F0ApYlRoPZw9lpuShFgNbByPTz7Xoko9PWM,5283
+bencode2-0.3.27.dist-info/WHEEL,sha256=HxTT_sQ360-hdmVNeweyxE6Ly6SvGGdMmSsv6PXi_1M,85
+bencode2/__bencode.cp313-win_arm64.pyd,sha256=WeFAIO2gGRAy5dlebXgqWbq3EmxwPv8_Cek70AiysQo,191488
+bencode2/__init__.py,sha256=z2lFW5z2l6pTccyzUGXkfFEcxqYwVgZ-iRuqrYC70bE,400
+bencode2/__init__.pyi,sha256=9IRJDThFEll3bdqQTH56r9y0bpI-D3qN5VM1LIRpX04,245
+bencode2/__encoder.py,sha256=ISaM-PLNdv8BKQFTq8YC_28czys9a0PbxzykCESYrKo,4355
+bencode2/__decoder.py,sha256=drQInAg7UdKhfJgXI-40r3tPUvS20ep65lmcAGkGp9M,6398
+bencode2/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bencode2-0.3.27.dist-info/RECORD,,

bencode2-0.3.27.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: meson
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_arm64