PyBen API Reference

pyben

PyBen is a library for decoding/encoding data, with the bencode specification.

Bencode is commonly used for encoding Bittorrent Protocol Metafiles (.torrent).

Modules

  • api
  • classes
  • bencode

Classes

  • Bendecoder
  • Benencoder

Functions

  • bendecode
  • benencode
  • dump
  • dumps
  • load
  • loads
  • readinto

Bendecoder

Decode class contains all decode methods.

Source code in pyben\classes.py 
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
class Bendecoder:
    """Decode class contains all decode methods."""

    def __init__(self, data: bytes = None):
        """
        Initialize instance with optional pre compiled data.

        Parameters
        ----------
        data : bytes
            (Optional) (default=None) Target data for decoding.
        """
        self.data = data
        self.decoded = None

    @classmethod
    def load(cls, item: str) -> dict:
        """
        Extract contents from path/path-like and return Decoded data.

        Parameters
        ----------
        item : str
            Path containing bencoded data.

        Raises
        ------
        FilePathError
            Incorrect path or IOBuffer doesnt exist.

        Returns
        -------
        any
            Decoded contents of file, Usually a dictionary.
        """
        decoder = cls()
        if hasattr(item, "read"):
            data = item.read()

        elif os.path.exists(item) and os.path.isfile(item):
            with open(item, "rb") as _fd:
                data = _fd.read()
        return decoder.decode(data)

    @classmethod
    def loads(cls, data: bytes) -> dict:
        """
        Shortcut to Decode raw bencoded data.

        Parameters
        ----------
        data : bytes
            Bendencoded bytes

        Returns
        -------
        any
            Decoded data usually a dictionary.
        """
        decoder = cls()
        return decoder.decode(data)

    def decode(self, data: bytes = None) -> dict:
        """
        Decode bencoded data.

        Parameters
        ----------
        data : bytes
            bencoded data for decoding.

        Returns
        -------
        any
            the decoded data.
        """
        data = self.data if not data else data
        self.decoded, _ = self._decode(bits=data)
        return self.decoded

    def _decode(self, bits: bytes = None) -> dict:
        """
        Decode bencoded data.

        Parameters
        ----------
        bits : bytes
            Bencoded data for decoding.

        Returns
        -------
        dict
            The decoded data.
        """
        if bits.startswith(b"i"):
            match, feed = self._decode_int(bits)
            return match, feed

        # decode string
        if chr(bits[0]).isdigit():
            num, feed = self._decode_str(bits)
            return num, feed

        # decode list and contents
        if bits.startswith(b"l"):
            lst, feed = self._decode_list(bits)
            return lst, feed

        # decode dictionary and contents
        if bits.startswith(b"d"):
            dic, feed = self._decode_dict(bits)
            return dic, feed

        raise DecodeError(bits)

    def _decode_dict(self, bits: bytes) -> dict:
        """
        Decode keys and values in dictionary.

        Parameters
        ----------
        bits : bytes
            `Bytes` of data for decoding.

        Returns
        -------
        dict
            Dictionary and contents.

        """
        dct, feed = {}, 1
        while not bits[feed:].startswith(b"e"):
            match1, rest = self._decode(bits[feed:])
            feed += rest
            match2, rest = self._decode(bits[feed:])
            feed += rest
            dct[match1] = match2
        feed += 1
        return dct, feed

    def _decode_list(self, data: bytes) -> list:
        """
        Decode list and its contents.

        Parameters
        ----------
        data : bytes
            Bencoded data.

        Returns
        -------
        list
            decoded list and contents
        """
        seq, feed = [], 1
        while not data[feed:].startswith(b"e"):
            match, rest = self._decode(data[feed:])
            seq.append(match)
            feed += rest
        feed += 1
        return seq, feed

    @staticmethod
    def _decode_str(bits: bytes) -> str:
        """
        Decode string.

        Parameters
        ----------
        bits : bytes
            Bencoded string.

        Returns
        -------
        str
            Decoded string.
        """
        match = re.match(rb"(\d+):", bits)
        word_size, start = int(match.groups()[0]), match.span()[1]
        finish = start + word_size
        word = bits[start:finish]

        try:
            word = word.decode("utf-8")

        except UnicodeDecodeError:
            pass

        return word, finish

    @staticmethod
    def _decode_int(bits: bytes) -> int:
        """
        Decode integer type.

        Parameters
        ----------
        bits : bytes
            Bencoded intiger.

        Returns
        -------
        int
            Decoded intiger.
        """
        obj = re.match(rb"i(-?\d+)e", bits)
        return int(obj.group(1)), obj.end()

__init__(data=None)

Initialize instance with optional pre compiled data.

Parameters:

Name Type Description Default
data bytes

(Optional) (default=None) Target data for decoding.

 None
Source code in pyben\classes.py 
35
36
37
38
39
40
41
42
43
44
45
def __init__(self, data: bytes = None):
    """
    Initialize instance with optional pre compiled data.

    Parameters
    ----------
    data : bytes
        (Optional) (default=None) Target data for decoding.
    """
    self.data = data
    self.decoded = None

decode(data=None)

Decode bencoded data.

Parameters:

Name Type Description Default
data bytes

bencoded data for decoding.

 None

Returns:

Type Description
any

the decoded data.
Source code in pyben\classes.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def decode(self, data: bytes = None) -> dict:
    """
    Decode bencoded data.

    Parameters
    ----------
    data : bytes
        bencoded data for decoding.

    Returns
    -------
    any
        the decoded data.
    """
    data = self.data if not data else data
    self.decoded, _ = self._decode(bits=data)
    return self.decoded

load(item) classmethod

Extract contents from path/path-like and return Decoded data.

Parameters:

Name Type Description Default
item str

Path containing bencoded data.

 required

Raises:

Type Description
FilePathError

Incorrect path or IOBuffer doesnt exist.

Returns:

Type Description
any

Decoded contents of file, Usually a dictionary.
Source code in pyben\classes.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@classmethod
def load(cls, item: str) -> dict:
    """
    Extract contents from path/path-like and return Decoded data.

    Parameters
    ----------
    item : str
        Path containing bencoded data.

    Raises
    ------
    FilePathError
        Incorrect path or IOBuffer doesnt exist.

    Returns
    -------
    any
        Decoded contents of file, Usually a dictionary.
    """
    decoder = cls()
    if hasattr(item, "read"):
        data = item.read()

    elif os.path.exists(item) and os.path.isfile(item):
        with open(item, "rb") as _fd:
            data = _fd.read()
    return decoder.decode(data)

loads(data) classmethod

Shortcut to Decode raw bencoded data.

Parameters:

Name Type Description Default
data bytes

Bendencoded bytes

 required

Returns:

Type Description
any

Decoded data usually a dictionary.
Source code in pyben\classes.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@classmethod
def loads(cls, data: bytes) -> dict:
    """
    Shortcut to Decode raw bencoded data.

    Parameters
    ----------
    data : bytes
        Bendencoded bytes

    Returns
    -------
    any
        Decoded data usually a dictionary.
    """
    decoder = cls()
    return decoder.decode(data)

Benencoder

Encoder for bencode encoding used for Bittorrent meta-files.

Source code in pyben\classes.py 
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
class Benencoder:
    """Encoder for bencode encoding used for Bittorrent meta-files."""

    def __init__(self, data: bytes = None):
        """
        Construct the Bencoder class.

        Parameters
        ----------
        data : bytes, optional
            data, by default None
        """
        self.data = data
        self.encoded = None

    @classmethod
    def dump(cls, data: bytes, path: os.PathLike) -> bool:
        """
        Shortcut class method for encoding data and writing to file.

        Parameters
        ----------
        data : any
            Raw data to be encoded, usually dict.txt
        path : os.PathLike
            Where encoded data should be written to.py

        Returns
        -------
        bool
            Return True if success.txt
        """
        encoded = cls(data).encode()
        if hasattr(path, "write"):
            path.write(encoded)
        else:
            with open(path, "wb") as _fd:
                _fd.write(encoded)
        return True

    @classmethod
    def dumps(cls, data) -> bytes:
        """
        Shortcut method for encoding data and immediately returning it.

        Parameters
        ----------
        data : any
            Raw data to be encoded usually a dictionary.

        Returns
        -------
        bytes
            Encoded data.
        """
        return cls(data).encode()

    def encode(self, val=None) -> bytes:
        """
        Encode data provided as an arguement or provided at initialization.

        Parameters
        ----------
        val : any, optional
            Data for encoding. Defaults to None.

        Returns
        -------
        bytes
            encoded data
        """
        if val is None:
            val = self.data
        self.encoded = self._encode(val)
        return self.encoded

    def _encode(self, val: bytes):
        """
        Encode data with bencode protocol.

        Parameters
        ----------
        val : bytes
            Bencoded data for decoding.

        Returns
        -------
        any
            the decoded data.
        """
        if isinstance(val, str):
            return self._encode_str(val)

        if hasattr(val, "hex"):
            return self._encode_bytes(val)

        if isinstance(val, int):
            return self._encode_int(val)

        if isinstance(val, list):
            return self._encode_list(val)

        if isinstance(val, dict):
            return self._encode_dict(val)

        if isinstance(val, tuple):
            return self._encode_list(list(val))

        raise EncodeError(val)

    @staticmethod
    def _encode_bytes(val: bytes) -> bytes:
        """
        Bencode encoding bytes as string literal.

        Parameters
        ----------
        val : bytes
            data

        Returns
        -------
        bytes
            data
        """
        size = str(len(val)) + ":"
        return size.encode("utf-8") + val

    @staticmethod
    def _encode_str(txt: str) -> bytes:
        """
        Decode string.

        Parameters
        ----------
        txt : str
            Any string literal.

        Returns
        -------
        bytes
            Bencoded string.
        """
        size = str(len(txt)).encode("utf-8")
        return size + b":" + txt.encode("utf-8")

    @staticmethod
    def _encode_int(num: int) -> bytes:
        """
        Encode intiger.

        Parameters
        ----------
        num : int
            Integer for encoding.

        Returns
        -------
        bytes
            Bencoded intiger.
        """
        return b"i" + str(num).encode("utf-8") + b"e"

    def _encode_list(self, elems: list) -> bytes:
        """
        Encode list and its contents.

        Parameters
        ----------
        elems : list
            List of content to be encoded.

        Returns
        -------
        bytes
            Bencoded data
        """
        lst = [b"l"]
        for elem in elems:
            encoded = self._encode(elem)
            lst.append(encoded)
        lst.append(b"e")
        bit_lst = b"".join(lst)
        return bit_lst

    def _encode_dict(self, dic: dict) -> bytes:
        """
        Encode keys and values in dictionary.

        Parameters
        ----------
        dic : dict
            Dictionary of data for encoding.

        Returns
        -------
        bytes
            Bencoded data.
        """
        result = b"d"
        for key, val in dic.items():
            result += b"".join([self._encode(key), self._encode(val)])
        return result + b"e"

__init__(data=None)

Construct the Bencoder class.

Parameters:

Name Type Description Default
data bytes, optional

data, by default None

 None
Source code in pyben\classes.py 
244
245
246
247
248
249
250
251
252
253
254
def __init__(self, data: bytes = None):
    """
    Construct the Bencoder class.

    Parameters
    ----------
    data : bytes, optional
        data, by default None
    """
    self.data = data
    self.encoded = None

dump(data, path) classmethod

Shortcut class method for encoding data and writing to file.

Parameters:

Name Type Description Default
data any

Raw data to be encoded, usually dict.txt

 required
path os.PathLike

Where encoded data should be written to.py

 required

Returns:

Type Description
bool

Return True if success.txt
Source code in pyben\classes.py 
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
@classmethod
def dump(cls, data: bytes, path: os.PathLike) -> bool:
    """
    Shortcut class method for encoding data and writing to file.

    Parameters
    ----------
    data : any
        Raw data to be encoded, usually dict.txt
    path : os.PathLike
        Where encoded data should be written to.py

    Returns
    -------
    bool
        Return True if success.txt
    """
    encoded = cls(data).encode()
    if hasattr(path, "write"):
        path.write(encoded)
    else:
        with open(path, "wb") as _fd:
            _fd.write(encoded)
    return True

dumps(data) classmethod

Shortcut method for encoding data and immediately returning it.

Parameters:

Name Type Description Default
data any

Raw data to be encoded usually a dictionary.

 required

Returns:

Type Description
bytes

Encoded data.
Source code in pyben\classes.py 
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
@classmethod
def dumps(cls, data) -> bytes:
    """
    Shortcut method for encoding data and immediately returning it.

    Parameters
    ----------
    data : any
        Raw data to be encoded usually a dictionary.

    Returns
    -------
    bytes
        Encoded data.
    """
    return cls(data).encode()

encode(val=None)

Encode data provided as an arguement or provided at initialization.

Parameters:

Name Type Description Default
val any, optional

Data for encoding. Defaults to None.

 None

Returns:

Type Description
bytes

encoded data
Source code in pyben\classes.py 
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
def encode(self, val=None) -> bytes:
    """
    Encode data provided as an arguement or provided at initialization.

    Parameters
    ----------
    val : any, optional
        Data for encoding. Defaults to None.

    Returns
    -------
    bytes
        encoded data
    """
    if val is None:
        val = self.data
    self.encoded = self._encode(val)
    return self.encoded

DecodeError

Bases: Exception

Error occured during decode process.

Raised when attempting to decode an incompatible bytearray. Mostly it indicates the object is a hash digest and should remian as a bytes object.

Parameters:

Name Type Description Default
val None

Value that cause the exception

 None
Source code in pyben\exceptions.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class DecodeError(Exception):
    """
    Error occured during decode process.

    Raised when attempting to decode an incompatible bytearray.
    Mostly it indicates the object is a hash digest and should remian
    as a bytes object.

    Parameters
    ----------
    val : None
        Value that cause the exception
    """

    def __init__(self, val=None):
        """Construct Exception DecodeError."""
        msg = f"Unable to decode invalid {type(val)} type = {str(val)}"
        super().__init__(msg)

__init__(val=None)

Construct Exception DecodeError.

Source code in pyben\exceptions.py 
31
32
33
34
def __init__(self, val=None):
    """Construct Exception DecodeError."""
    msg = f"Unable to decode invalid {type(val)} type = {str(val)}"
    super().__init__(msg)

EncodeError

Bases: Exception

Error occured during encoding process.

Raised when attempting to bencode encode an incompatible data type into bencode format. Bencode accepts lists, dicts, strings, integers, and bytes.

Parameters:

Name Type Description Default
val None

Value that cause the exception

 None
Source code in pyben\exceptions.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class EncodeError(Exception):
    """
    Error occured during encoding process.

    Raised when attempting to bencode encode an incompatible
    data type into bencode format. Bencode accepts lists, dicts,
    strings, integers, and bytes.

    Parameters
    ----------
    val : None
        Value that cause the exception
    """

    def __init__(self, val=None):
        """Construct Exception EncodeError."""
        msg = f"Encoder is unable to interpret {type(val)} type = {str(val)}"
        super().__init__(msg)

__init__(val=None)

Construct Exception EncodeError.

Source code in pyben\exceptions.py 
51
52
53
54
def __init__(self, val=None):
    """Construct Exception EncodeError."""
    msg = f"Encoder is unable to interpret {type(val)} type = {str(val)}"
    super().__init__(msg)

FilePathError

Bases: Exception

Bad path error.

Generally raised when the file at the path specified does not exist.

Parameters:

Name Type Description Default
obj None

Value that cause the exception

 None
Source code in pyben\exceptions.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class FilePathError(Exception):
    """Bad path error.

    Generally raised when the file at the path specified
    does not exist.

    Parameters
    ----------
    obj : None
        Value that cause the exception
    """

    def __init__(self, obj=None):
        """Construct Exception Subclass FilePathError."""
        msg = f"{str(obj)} doesn't exist or is unavailable."
        super().__init__(msg)

__init__(obj=None)

Construct Exception Subclass FilePathError.

Source code in pyben\exceptions.py 
69
70
71
72
def __init__(self, obj=None):
    """Construct Exception Subclass FilePathError."""
    msg = f"{str(obj)} doesn't exist or is unavailable."
    super().__init__(msg)

bendecode(bits)

Decode bencoded data.

Parameters:

Name Type Description Default
bits bytes

Bencode encoded data.

 required

Raises:

Type Description
DecodeError

Malformed data.

Returns:

Type Description
tuple

Bencode decoded data.
Source code in pyben\bencode.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def bendecode(bits: bytes) -> tuple:
    """
    Decode bencoded data.

    Parameters
    ----------
    bits : bytes
        Bencode encoded data.

    Raises
    ------
    DecodeError
        Malformed data.

    Returns
    -------
    tuple
        Bencode decoded data.
    """
    if bits.startswith(b"i"):
        match, feed = bendecode_int(bits)
        return match, feed

    if chr(bits[0]).isdigit():
        match, feed = bendecode_str(bits)
        return match, feed

    if bits.startswith(b"l"):
        lst, feed = bendecode_list(bits)
        return lst, feed

    if bits.startswith(b"d"):
        dic, feed = bendecode_dict(bits)
        return dic, feed

    raise DecodeError(bits)

benencode(val)

Encode data with bencoding.

Parameters:

Name Type Description Default
val any

Data for encoding.

 required

Raises:

Type Description
EncodeError

Cannot interpret data.

Returns:

Type Description
bytes

Bencoded data.
Source code in pyben\bencode.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def benencode(val) -> bytes:
    """
    Encode data with bencoding.

    Parameters
    ----------
    val : any
        Data for encoding.

    Raises
    ------
    EncodeError
        Cannot interpret data.

    Returns
    -------
    bytes
        Bencoded data.
    """
    if isinstance(val, str):
        return bencode_str(val)

    if isinstance(val, int):
        return bencode_int(val)

    if isinstance(val, list):
        return bencode_list(val)

    if isinstance(val, dict):
        return bencode_dict(val)

    if hasattr(val, "hex"):
        return bencode_bytes(val)

    if isinstance(val, tuple):
        return bencode_list(list(val))

    raise EncodeError(val)

dump(obj, buffer)

Shortcut function for bencode encode data and write to file.

Works effectively the same as it's json equivelant except also accepts a path as well as an open fileIO.

Parameters:

Name Type Description Default
obj any

Data to be encoded.

 required
buffer str or BytesIO

File of path-like to write the data to.

 required
Source code in pyben\api.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def dump(obj, buffer):
    """
    Shortcut function for bencode encode data and write to file.

    Works effectively the same as it's json equivelant except also
    accepts a path as well as an open fileIO.

    Parameters
    ----------
    obj : any
        Data to be encoded.
    buffer : str or BytesIO
        File of path-like to write the data to.
    """
    encoded = benencode(obj)

    if not hasattr(buffer, "write"):
        if hasattr(buffer, "decode"):  # pragma: nocover
            txt = buffer.decode("utf-8")
        else:
            txt = buffer
        with open(txt, "wb") as _fd:
            _fd.write(encoded)
    else:
        buffer.write(encoded)

dumps(obj)

Shortuct function to encoding given obj to bencode encoding.

Parameters:

Name Type Description Default
obj any

Object to be encoded.py.

 required

Returns:

Name Type Description
bytes

Encoded data.
Source code in pyben\api.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def dumps(obj):
    """
    Shortuct function to encoding given obj to bencode encoding.

    Parameters
    ----------
    obj : any
        Object to be encoded.py.

    Returns
    -------
    bytes :
        Encoded data.
    """
    return bytes(benencode(obj))

load(buffer, to_json=False)

Load bencoded data from a file of path object and decodes it.

Parameters:

Name Type Description Default
buffer str

Open and/or read data from file to be decoded.

 required
to_json bool

convert to json serializable metadata if True else leave it alone.

 False

Returns:

Name Type Description
dict

(commonly dict), Decoded contents of file.
Source code in pyben\api.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def load(buffer, to_json=False):
    """
    Load bencoded data from a file of path object and decodes it.

    Parameters
    ----------
    buffer : str
        Open and/or read data from file to be decoded.
    to_json : bool
        convert to json serializable metadata if True else leave it alone.

    Returns
    -------
    dict :
        (commonly `dict`), Decoded contents of file.
    """
    if buffer in [None, ""]:
        raise FilePathError(buffer)

    if hasattr(buffer, "read"):
        decoded, _ = bendecode(buffer.read())
    else:
        if hasattr(buffer, "decode"):  # pragma: nocover
            path = buffer.decode("utf-8")
        else:
            path = buffer
        try:
            with open(path, "rb") as _fd:
                decoded, _ = bendecode(_fd.read())
        except (FileNotFoundError, IsADirectoryError, PermissionError) as err:
            raise FilePathError(buffer) from err
    if to_json:
        decoded = _to_json(decoded)
    return decoded

loadinto(buffer, lst)

Shortcut function to load becoded data from file and store it in list.

This function is most useful for multithreading purposes.

Parameters:

Name Type Description Default
buffer str

string or open file buffer.

 required
lst list

variable to store output into

 required

Returns:

Name Type Description
list

the list containing the output.
Source code in pyben\api.py 
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
def loadinto(buffer, lst):
    """
    Shortcut function to load becoded data from file and store it in list.

    This function is most useful for multithreading purposes.

    Parameters
    ----------
    buffer : str
        string or open file buffer.
    lst : list
        variable to store output into

    Returns
    -------
    list :
        the list containing the output.
    """
    try:
        output = load(buffer)
        lst.append(output)
    except FilePathError as err:
        lst.append(False)
        raise FilePathError from err
    return lst

loads(encoded, to_json=False)

Shortcut function for decoding encoded data.

Parameters:

Name Type Description Default
encoded bytes

Bencoded data.

 required
to_json bool

Convert to json serializable if true otherwise leave it alone.

 False

Returns:

Name Type Description
dict

(any), Decoded data.
Source code in pyben\api.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def loads(encoded, to_json=False):
    """
    Shortcut function for decoding encoded data.

    Parameters
    ----------
    encoded : bytes
        Bencoded data.
    to_json : bool
        Convert to json serializable if true otherwise leave it alone.

    Returns
    -------
    dict :
        (any), Decoded data.
    """
    decoded, _ = bendecode(encoded)
    if to_json:
        decoded = _to_json(decoded)
    return decoded

show(inp)

Ouptut readable metadata.

Parameters:

Name Type Description Default
inp any

Pre-formatted input type.

 required

Returns:

Name Type Description
bool

Returns True if completed successfully.
Source code in pyben\api.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
def show(inp):
    """
    Ouptut readable metadata.

    Parameters
    ----------
    inp : any
        Pre-formatted input type.

    Returns
    -------
    bool :
        Returns True if completed successfully.
    """
    import json
    import os
    import sys

    if isinstance(inp, dict):
        meta = _to_json(inp)
    elif hasattr(inp, "read"):
        meta = load(inp, to_json=True)

    elif isinstance(inp, (str, os.PathLike)):
        try:
            meta = load(inp, to_json=True)
        except FilePathError:
            meta = inp
    elif isinstance(inp, (bytes, bytearray)):
        meta = loads(inp, to_json=True)

    json.dump(meta, sys.stdout, indent=4)
    return True

pyben.api

Bencode utility library.

Features simple API inspired by json and pickle modules in stdlib.

Functions

  • dump
  • dumps
  • load
  • loads
  • tojson

Examples:

Usage Examples

Encode inline code:
>>> import os
>>> import pyben
>>> data = {"item1": ["item2", 3, [4], {5: "item6"}]}
>>> encoded = pyben.dumps(data)
>>> encoded
... b'd5:item1l5:item2i3eli4eedi5e5:item6eee'
Encode to file:
>>> fd = "path/to/file"
>>> pyben.dump(data, fd)
>>> os.path.exists(fd)
... True
>>> encoded_file = open(fd, "rb").read()
>>> encoded_file == encoded
... True
Decode inline code:
>>> decoded = pybem.loads(encoded)
>>> decoded
... {'item1': ['item2', 3, [4], {5: 'item6'}]}
>>> decoded == data
... True
Decode from file:
>>> decoded_file = pyben.load(fd)
>>> decoded_file
... {'item1': ['item2', 3, [4], {5: 'item6'}]}
>>> decoded_file == data
... True

dump(obj, buffer)

Shortcut function for bencode encode data and write to file.

Works effectively the same as it's json equivelant except also accepts a path as well as an open fileIO.

Parameters:

Name Type Description Default
obj any

Data to be encoded.

 required
buffer str or BytesIO

File of path-like to write the data to.

 required
Source code in pyben\api.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def dump(obj, buffer):
    """
    Shortcut function for bencode encode data and write to file.

    Works effectively the same as it's json equivelant except also
    accepts a path as well as an open fileIO.

    Parameters
    ----------
    obj : any
        Data to be encoded.
    buffer : str or BytesIO
        File of path-like to write the data to.
    """
    encoded = benencode(obj)

    if not hasattr(buffer, "write"):
        if hasattr(buffer, "decode"):  # pragma: nocover
            txt = buffer.decode("utf-8")
        else:
            txt = buffer
        with open(txt, "wb") as _fd:
            _fd.write(encoded)
    else:
        buffer.write(encoded)

dumps(obj)

Shortuct function to encoding given obj to bencode encoding.

Parameters:

Name Type Description Default
obj any

Object to be encoded.py.

 required

Returns:

Name Type Description
bytes

Encoded data.
Source code in pyben\api.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def dumps(obj):
    """
    Shortuct function to encoding given obj to bencode encoding.

    Parameters
    ----------
    obj : any
        Object to be encoded.py.

    Returns
    -------
    bytes :
        Encoded data.
    """
    return bytes(benencode(obj))

load(buffer, to_json=False)

Load bencoded data from a file of path object and decodes it.

Parameters:

Name Type Description Default
buffer str

Open and/or read data from file to be decoded.

 required
to_json bool

convert to json serializable metadata if True else leave it alone.

 False

Returns:

Name Type Description
dict

(commonly dict), Decoded contents of file.
Source code in pyben\api.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def load(buffer, to_json=False):
    """
    Load bencoded data from a file of path object and decodes it.

    Parameters
    ----------
    buffer : str
        Open and/or read data from file to be decoded.
    to_json : bool
        convert to json serializable metadata if True else leave it alone.

    Returns
    -------
    dict :
        (commonly `dict`), Decoded contents of file.
    """
    if buffer in [None, ""]:
        raise FilePathError(buffer)

    if hasattr(buffer, "read"):
        decoded, _ = bendecode(buffer.read())
    else:
        if hasattr(buffer, "decode"):  # pragma: nocover
            path = buffer.decode("utf-8")
        else:
            path = buffer
        try:
            with open(path, "rb") as _fd:
                decoded, _ = bendecode(_fd.read())
        except (FileNotFoundError, IsADirectoryError, PermissionError) as err:
            raise FilePathError(buffer) from err
    if to_json:
        decoded = _to_json(decoded)
    return decoded

loadinto(buffer, lst)

Shortcut function to load becoded data from file and store it in list.

This function is most useful for multithreading purposes.

Parameters:

Name Type Description Default
buffer str

string or open file buffer.

 required
lst list

variable to store output into

 required

Returns:

Name Type Description
list

the list containing the output.
Source code in pyben\api.py 
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
def loadinto(buffer, lst):
    """
    Shortcut function to load becoded data from file and store it in list.

    This function is most useful for multithreading purposes.

    Parameters
    ----------
    buffer : str
        string or open file buffer.
    lst : list
        variable to store output into

    Returns
    -------
    list :
        the list containing the output.
    """
    try:
        output = load(buffer)
        lst.append(output)
    except FilePathError as err:
        lst.append(False)
        raise FilePathError from err
    return lst

loads(encoded, to_json=False)

Shortcut function for decoding encoded data.

Parameters:

Name Type Description Default
encoded bytes

Bencoded data.

 required
to_json bool

Convert to json serializable if true otherwise leave it alone.

 False

Returns:

Name Type Description
dict

(any), Decoded data.
Source code in pyben\api.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def loads(encoded, to_json=False):
    """
    Shortcut function for decoding encoded data.

    Parameters
    ----------
    encoded : bytes
        Bencoded data.
    to_json : bool
        Convert to json serializable if true otherwise leave it alone.

    Returns
    -------
    dict :
        (any), Decoded data.
    """
    decoded, _ = bendecode(encoded)
    if to_json:
        decoded = _to_json(decoded)
    return decoded

show(inp)

Ouptut readable metadata.

Parameters:

Name Type Description Default
inp any

Pre-formatted input type.

 required

Returns:

Name Type Description
bool

Returns True if completed successfully.
Source code in pyben\api.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
def show(inp):
    """
    Ouptut readable metadata.

    Parameters
    ----------
    inp : any
        Pre-formatted input type.

    Returns
    -------
    bool :
        Returns True if completed successfully.
    """
    import json
    import os
    import sys

    if isinstance(inp, dict):
        meta = _to_json(inp)
    elif hasattr(inp, "read"):
        meta = load(inp, to_json=True)

    elif isinstance(inp, (str, os.PathLike)):
        try:
            meta = load(inp, to_json=True)
        except FilePathError:
            meta = inp
    elif isinstance(inp, (bytes, bytearray)):
        meta = loads(inp, to_json=True)

    json.dump(meta, sys.stdout, indent=4)
    return True

pyben.classes

OOP implementation of bencode decoders and encoders.

This style is not recommended as it can get bulky. The json-like api from the bencode.py module is much easier to use.

Classes

  • Bendecoder
  • Benencoder

Bendecoder

Decode class contains all decode methods.

Source code in pyben\classes.py 
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
class Bendecoder:
    """Decode class contains all decode methods."""

    def __init__(self, data: bytes = None):
        """
        Initialize instance with optional pre compiled data.

        Parameters
        ----------
        data : bytes
            (Optional) (default=None) Target data for decoding.
        """
        self.data = data
        self.decoded = None

    @classmethod
    def load(cls, item: str) -> dict:
        """
        Extract contents from path/path-like and return Decoded data.

        Parameters
        ----------
        item : str
            Path containing bencoded data.

        Raises
        ------
        FilePathError
            Incorrect path or IOBuffer doesnt exist.

        Returns
        -------
        any
            Decoded contents of file, Usually a dictionary.
        """
        decoder = cls()
        if hasattr(item, "read"):
            data = item.read()

        elif os.path.exists(item) and os.path.isfile(item):
            with open(item, "rb") as _fd:
                data = _fd.read()
        return decoder.decode(data)

    @classmethod
    def loads(cls, data: bytes) -> dict:
        """
        Shortcut to Decode raw bencoded data.

        Parameters
        ----------
        data : bytes
            Bendencoded bytes

        Returns
        -------
        any
            Decoded data usually a dictionary.
        """
        decoder = cls()
        return decoder.decode(data)

    def decode(self, data: bytes = None) -> dict:
        """
        Decode bencoded data.

        Parameters
        ----------
        data : bytes
            bencoded data for decoding.

        Returns
        -------
        any
            the decoded data.
        """
        data = self.data if not data else data
        self.decoded, _ = self._decode(bits=data)
        return self.decoded

    def _decode(self, bits: bytes = None) -> dict:
        """
        Decode bencoded data.

        Parameters
        ----------
        bits : bytes
            Bencoded data for decoding.

        Returns
        -------
        dict
            The decoded data.
        """
        if bits.startswith(b"i"):
            match, feed = self._decode_int(bits)
            return match, feed

        # decode string
        if chr(bits[0]).isdigit():
            num, feed = self._decode_str(bits)
            return num, feed

        # decode list and contents
        if bits.startswith(b"l"):
            lst, feed = self._decode_list(bits)
            return lst, feed

        # decode dictionary and contents
        if bits.startswith(b"d"):
            dic, feed = self._decode_dict(bits)
            return dic, feed

        raise DecodeError(bits)

    def _decode_dict(self, bits: bytes) -> dict:
        """
        Decode keys and values in dictionary.

        Parameters
        ----------
        bits : bytes
            `Bytes` of data for decoding.

        Returns
        -------
        dict
            Dictionary and contents.

        """
        dct, feed = {}, 1
        while not bits[feed:].startswith(b"e"):
            match1, rest = self._decode(bits[feed:])
            feed += rest
            match2, rest = self._decode(bits[feed:])
            feed += rest
            dct[match1] = match2
        feed += 1
        return dct, feed

    def _decode_list(self, data: bytes) -> list:
        """
        Decode list and its contents.

        Parameters
        ----------
        data : bytes
            Bencoded data.

        Returns
        -------
        list
            decoded list and contents
        """
        seq, feed = [], 1
        while not data[feed:].startswith(b"e"):
            match, rest = self._decode(data[feed:])
            seq.append(match)
            feed += rest
        feed += 1
        return seq, feed

    @staticmethod
    def _decode_str(bits: bytes) -> str:
        """
        Decode string.

        Parameters
        ----------
        bits : bytes
            Bencoded string.

        Returns
        -------
        str
            Decoded string.
        """
        match = re.match(rb"(\d+):", bits)
        word_size, start = int(match.groups()[0]), match.span()[1]
        finish = start + word_size
        word = bits[start:finish]

        try:
            word = word.decode("utf-8")

        except UnicodeDecodeError:
            pass

        return word, finish

    @staticmethod
    def _decode_int(bits: bytes) -> int:
        """
        Decode integer type.

        Parameters
        ----------
        bits : bytes
            Bencoded intiger.

        Returns
        -------
        int
            Decoded intiger.
        """
        obj = re.match(rb"i(-?\d+)e", bits)
        return int(obj.group(1)), obj.end()

__init__(data=None)

Initialize instance with optional pre compiled data.

Parameters:

Name Type Description Default
data bytes

(Optional) (default=None) Target data for decoding.

 None
Source code in pyben\classes.py 
35
36
37
38
39
40
41
42
43
44
45
def __init__(self, data: bytes = None):
    """
    Initialize instance with optional pre compiled data.

    Parameters
    ----------
    data : bytes
        (Optional) (default=None) Target data for decoding.
    """
    self.data = data
    self.decoded = None

decode(data=None)

Decode bencoded data.

Parameters:

Name Type Description Default
data bytes

bencoded data for decoding.

 None

Returns:

Type Description
any

the decoded data.
Source code in pyben\classes.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def decode(self, data: bytes = None) -> dict:
    """
    Decode bencoded data.

    Parameters
    ----------
    data : bytes
        bencoded data for decoding.

    Returns
    -------
    any
        the decoded data.
    """
    data = self.data if not data else data
    self.decoded, _ = self._decode(bits=data)
    return self.decoded

load(item) classmethod

Extract contents from path/path-like and return Decoded data.

Parameters:

Name Type Description Default
item str

Path containing bencoded data.

 required

Raises:

Type Description
FilePathError

Incorrect path or IOBuffer doesnt exist.

Returns:

Type Description
any

Decoded contents of file, Usually a dictionary.
Source code in pyben\classes.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@classmethod
def load(cls, item: str) -> dict:
    """
    Extract contents from path/path-like and return Decoded data.

    Parameters
    ----------
    item : str
        Path containing bencoded data.

    Raises
    ------
    FilePathError
        Incorrect path or IOBuffer doesnt exist.

    Returns
    -------
    any
        Decoded contents of file, Usually a dictionary.
    """
    decoder = cls()
    if hasattr(item, "read"):
        data = item.read()

    elif os.path.exists(item) and os.path.isfile(item):
        with open(item, "rb") as _fd:
            data = _fd.read()
    return decoder.decode(data)

loads(data) classmethod

Shortcut to Decode raw bencoded data.

Parameters:

Name Type Description Default
data bytes

Bendencoded bytes

 required

Returns:

Type Description
any

Decoded data usually a dictionary.
Source code in pyben\classes.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@classmethod
def loads(cls, data: bytes) -> dict:
    """
    Shortcut to Decode raw bencoded data.

    Parameters
    ----------
    data : bytes
        Bendencoded bytes

    Returns
    -------
    any
        Decoded data usually a dictionary.
    """
    decoder = cls()
    return decoder.decode(data)

Benencoder

Encoder for bencode encoding used for Bittorrent meta-files.

Source code in pyben\classes.py 
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
class Benencoder:
    """Encoder for bencode encoding used for Bittorrent meta-files."""

    def __init__(self, data: bytes = None):
        """
        Construct the Bencoder class.

        Parameters
        ----------
        data : bytes, optional
            data, by default None
        """
        self.data = data
        self.encoded = None

    @classmethod
    def dump(cls, data: bytes, path: os.PathLike) -> bool:
        """
        Shortcut class method for encoding data and writing to file.

        Parameters
        ----------
        data : any
            Raw data to be encoded, usually dict.txt
        path : os.PathLike
            Where encoded data should be written to.py

        Returns
        -------
        bool
            Return True if success.txt
        """
        encoded = cls(data).encode()
        if hasattr(path, "write"):
            path.write(encoded)
        else:
            with open(path, "wb") as _fd:
                _fd.write(encoded)
        return True

    @classmethod
    def dumps(cls, data) -> bytes:
        """
        Shortcut method for encoding data and immediately returning it.

        Parameters
        ----------
        data : any
            Raw data to be encoded usually a dictionary.

        Returns
        -------
        bytes
            Encoded data.
        """
        return cls(data).encode()

    def encode(self, val=None) -> bytes:
        """
        Encode data provided as an arguement or provided at initialization.

        Parameters
        ----------
        val : any, optional
            Data for encoding. Defaults to None.

        Returns
        -------
        bytes
            encoded data
        """
        if val is None:
            val = self.data
        self.encoded = self._encode(val)
        return self.encoded

    def _encode(self, val: bytes):
        """
        Encode data with bencode protocol.

        Parameters
        ----------
        val : bytes
            Bencoded data for decoding.

        Returns
        -------
        any
            the decoded data.
        """
        if isinstance(val, str):
            return self._encode_str(val)

        if hasattr(val, "hex"):
            return self._encode_bytes(val)

        if isinstance(val, int):
            return self._encode_int(val)

        if isinstance(val, list):
            return self._encode_list(val)

        if isinstance(val, dict):
            return self._encode_dict(val)

        if isinstance(val, tuple):
            return self._encode_list(list(val))

        raise EncodeError(val)

    @staticmethod
    def _encode_bytes(val: bytes) -> bytes:
        """
        Bencode encoding bytes as string literal.

        Parameters
        ----------
        val : bytes
            data

        Returns
        -------
        bytes
            data
        """
        size = str(len(val)) + ":"
        return size.encode("utf-8") + val

    @staticmethod
    def _encode_str(txt: str) -> bytes:
        """
        Decode string.

        Parameters
        ----------
        txt : str
            Any string literal.

        Returns
        -------
        bytes
            Bencoded string.
        """
        size = str(len(txt)).encode("utf-8")
        return size + b":" + txt.encode("utf-8")

    @staticmethod
    def _encode_int(num: int) -> bytes:
        """
        Encode intiger.

        Parameters
        ----------
        num : int
            Integer for encoding.

        Returns
        -------
        bytes
            Bencoded intiger.
        """
        return b"i" + str(num).encode("utf-8") + b"e"

    def _encode_list(self, elems: list) -> bytes:
        """
        Encode list and its contents.

        Parameters
        ----------
        elems : list
            List of content to be encoded.

        Returns
        -------
        bytes
            Bencoded data
        """
        lst = [b"l"]
        for elem in elems:
            encoded = self._encode(elem)
            lst.append(encoded)
        lst.append(b"e")
        bit_lst = b"".join(lst)
        return bit_lst

    def _encode_dict(self, dic: dict) -> bytes:
        """
        Encode keys and values in dictionary.

        Parameters
        ----------
        dic : dict
            Dictionary of data for encoding.

        Returns
        -------
        bytes
            Bencoded data.
        """
        result = b"d"
        for key, val in dic.items():
            result += b"".join([self._encode(key), self._encode(val)])
        return result + b"e"

__init__(data=None)

Construct the Bencoder class.

Parameters:

Name Type Description Default
data bytes, optional

data, by default None

 None
Source code in pyben\classes.py 
244
245
246
247
248
249
250
251
252
253
254
def __init__(self, data: bytes = None):
    """
    Construct the Bencoder class.

    Parameters
    ----------
    data : bytes, optional
        data, by default None
    """
    self.data = data
    self.encoded = None

dump(data, path) classmethod

Shortcut class method for encoding data and writing to file.

Parameters:

Name Type Description Default
data any

Raw data to be encoded, usually dict.txt

 required
path os.PathLike

Where encoded data should be written to.py

 required

Returns:

Type Description
bool

Return True if success.txt
Source code in pyben\classes.py 
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
@classmethod
def dump(cls, data: bytes, path: os.PathLike) -> bool:
    """
    Shortcut class method for encoding data and writing to file.

    Parameters
    ----------
    data : any
        Raw data to be encoded, usually dict.txt
    path : os.PathLike
        Where encoded data should be written to.py

    Returns
    -------
    bool
        Return True if success.txt
    """
    encoded = cls(data).encode()
    if hasattr(path, "write"):
        path.write(encoded)
    else:
        with open(path, "wb") as _fd:
            _fd.write(encoded)
    return True

dumps(data) classmethod

Shortcut method for encoding data and immediately returning it.

Parameters:

Name Type Description Default
data any

Raw data to be encoded usually a dictionary.

 required

Returns:

Type Description
bytes

Encoded data.
Source code in pyben\classes.py 
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
@classmethod
def dumps(cls, data) -> bytes:
    """
    Shortcut method for encoding data and immediately returning it.

    Parameters
    ----------
    data : any
        Raw data to be encoded usually a dictionary.

    Returns
    -------
    bytes
        Encoded data.
    """
    return cls(data).encode()

encode(val=None)

Encode data provided as an arguement or provided at initialization.

Parameters:

Name Type Description Default
val any, optional

Data for encoding. Defaults to None.

 None

Returns:

Type Description
bytes

encoded data
Source code in pyben\classes.py 
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
def encode(self, val=None) -> bytes:
    """
    Encode data provided as an arguement or provided at initialization.

    Parameters
    ----------
    val : any, optional
        Data for encoding. Defaults to None.

    Returns
    -------
    bytes
        encoded data
    """
    if val is None:
        val = self.data
    self.encoded = self._encode(val)
    return self.encoded

pyben.bencode

API helper functions for decoding and encoding data with bencode format.

Functions

  • bendecode
  • bendecode_dict
  • bendecode_int
  • bendecode_list

  • bendecode_str

  • benencode

  • bencode_bytes
  • bencode_dict
  • bencode_int
  • bencode_list
  • bencode_str

bencode_bytes(bits)

Encode bytes.

Parameters:

Name Type Description Default
bits bytes

Bytes treated as a byte-string literal.

 required

Returns:

Type Description
bytes

Bencode encoded byte string literal.
Source code in pyben\bencode.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
def bencode_bytes(bits: bytes) -> bytes:
    """
    Encode bytes.

    Parameters
    ----------
    bits : bytes
        Bytes treated as a byte-string literal.

    Returns
    -------
    bytes
        Bencode encoded byte string literal.
    """
    size = str(len(bits)) + ":"
    return size.encode("utf-8") + bits

bencode_dict(dic)

Encode dictionary and contents.

Parameters:

Name Type Description Default
dic dict

Any dictionary containing items that can be bencoded.

 required

Returns:

Name Type Description
bytes bytes

Bencoded key, value pairs of data.
Source code in pyben\bencode.py 
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
def bencode_dict(dic: dict) -> bytes:
    """
    Encode dictionary and contents.

    Parameters
    ----------
    dic : dict
        Any dictionary containing items that can be bencoded.

    Returns
    -------
    bytes :
        Bencoded key, value pairs of data.
    """
    result = b"d"

    for key, val in dic.items():
        result += b"".join([benencode(key), benencode(val)])

    return result + b"e"

bencode_int(i)

Encode integer type.

Parameters:

Name Type Description Default
i int

Number that needs encoding.

 required

Returns:

Type Description
bytes

Bencoded Integer.
Source code in pyben\bencode.py 
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def bencode_int(i: int) -> bytes:
    """
    Encode integer type.

    Parameters
    ----------
    i : int
        Number that needs encoding.

    Returns
    -------
    bytes
        Bencoded Integer.
    """
    return ("i" + str(i) + "e").encode("utf-8")

bencode_list(elems)

Encode list and contents.

Parameters:

Name Type Description Default
elems list

List of items for bencoding.

 required

Returns:

Type Description
bytes

Bencoded list and contents.
Source code in pyben\bencode.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
def bencode_list(elems: list) -> bytes:
    """
    Encode list and contents.

    Parameters
    ----------
    elems : list
        List of items for bencoding.

    Returns
    -------
    bytes
        Bencoded list and contents.
    """
    arr = bytearray("l", encoding="utf-8")

    for elem in elems:
        encoded = benencode(elem)
        arr.extend(encoded)

    arr.extend(b"e")
    return arr

bencode_str(txt)

Encode string literals.

Parameters:

Name Type Description Default
txt str

Any text string.

 required

Returns:

Type Description
bytes

Bencoded string literal.
Source code in pyben\bencode.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
def bencode_str(txt: str) -> bytes:
    """
    Encode string literals.

    Parameters
    ----------
    txt : str
        Any text string.

    Returns
    -------
    bytes
        Bencoded string literal.
    """
    text = txt.encode("utf-8")
    size = str(len(text)) + ":"
    return size.encode("utf-8") + text

bendecode(bits)

Decode bencoded data.

Parameters:

Name Type Description Default
bits bytes

Bencode encoded data.

 required

Raises:

Type Description
DecodeError

Malformed data.

Returns:

Type Description
tuple

Bencode decoded data.
Source code in pyben\bencode.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def bendecode(bits: bytes) -> tuple:
    """
    Decode bencoded data.

    Parameters
    ----------
    bits : bytes
        Bencode encoded data.

    Raises
    ------
    DecodeError
        Malformed data.

    Returns
    -------
    tuple
        Bencode decoded data.
    """
    if bits.startswith(b"i"):
        match, feed = bendecode_int(bits)
        return match, feed

    if chr(bits[0]).isdigit():
        match, feed = bendecode_str(bits)
        return match, feed

    if bits.startswith(b"l"):
        lst, feed = bendecode_list(bits)
        return lst, feed

    if bits.startswith(b"d"):
        dic, feed = bendecode_dict(bits)
        return dic, feed

    raise DecodeError(bits)

bendecode_dict(bits)

Decode dictionary and it's contents.

Parameters:

Name Type Description Default
bits bytes

Bencoded dictionary.

 required

Returns:

Type Description
tuple

Decoded dictionary and contents
Source code in pyben\bencode.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def bendecode_dict(bits: bytes) -> tuple:
    """
    Decode dictionary and it's contents.

    Parameters
    ----------
    bits : bytes
        Bencoded dictionary.

    Returns
    -------
    tuple
        Decoded dictionary and contents
    """
    dic, feed = {}, 1

    while not bits[feed:].startswith(b"e"):
        match1, rest = bendecode(bits[feed:])
        feed += rest
        match2, rest = bendecode(bits[feed:])
        feed += rest
        dic[match1] = match2

    feed += 1
    return dic, feed

bendecode_int(bits)

Decode digits.

Parameters:

Name Type Description Default
bits bytes

Bencoded intiger bytes

 required

Returns:

Name Type Description
int int

Decoded int value.
Source code in pyben\bencode.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def bendecode_int(bits: bytes) -> int:
    """
    Decode digits.

    Parameters
    ----------
    bits : bytes
        Bencoded intiger bytes

    Returns
    -------
    int :
        Decoded int value.
    """
    obj = re.match(rb"i(-?\d+)e", bits)
    return int(obj.group(1)), obj.end()

bendecode_list(bits)

Decode list and list contents.

Parameters:

Name Type Description Default
bits bytes

Bencoded list.

 required

Returns:

Type Description
tuple

Bencode decoded list and contents.
Source code in pyben\bencode.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def bendecode_list(bits: bytes) -> tuple:
    """
    Decode list and list contents.

    Parameters
    ----------
    bits : bytes
        Bencoded list.

    Returns
    -------
    tuple
        Bencode decoded list and contents.
    """
    lst, feed = [], 1

    while not bits[feed:].startswith(b"e"):
        match, rest = bendecode(bits[feed:])
        lst.append(match)
        feed += rest

    feed += 1
    return lst, feed

bendecode_str(units)

Bendecode string types.

Parameters:

Name Type Description Default
units bytes

Bencoded string.

 required

Returns:

Type Description
str

Decoded data string.
Source code in pyben\bencode.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def bendecode_str(units: bytes) -> str:
    """
    Bendecode string types.

    Parameters
    ----------
    units : bytes
        Bencoded string.

    Returns
    -------
    str
        Decoded data string.

    """
    match = re.match(rb"(\d+):", units)
    word_len, start = int(match.groups()[0]), match.span()[1]
    end = start + word_len
    text = units[start:end]

    try:
        text = text.decode("utf-8")

    except UnicodeDecodeError:
        pass

    return text, end

benencode(val)

Encode data with bencoding.

Parameters:

Name Type Description Default
val any

Data for encoding.

 required

Raises:

Type Description
EncodeError

Cannot interpret data.

Returns:

Type Description
bytes

Bencoded data.
Source code in pyben\bencode.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def benencode(val) -> bytes:
    """
    Encode data with bencoding.

    Parameters
    ----------
    val : any
        Data for encoding.

    Raises
    ------
    EncodeError
        Cannot interpret data.

    Returns
    -------
    bytes
        Bencoded data.
    """
    if isinstance(val, str):
        return bencode_str(val)

    if isinstance(val, int):
        return bencode_int(val)

    if isinstance(val, list):
        return bencode_list(val)

    if isinstance(val, dict):
        return bencode_dict(val)

    if hasattr(val, "hex"):
        return bencode_bytes(val)

    if isinstance(val, tuple):
        return bencode_list(list(val))

    raise EncodeError(val)

pyben.exceptions

Exceptions used throughout the PyBen Package/Library.

DecodeError

Bases: Exception

Error occured during decode process.

Raised when attempting to decode an incompatible bytearray. Mostly it indicates the object is a hash digest and should remian as a bytes object.

Parameters:

Name Type Description Default
val None

Value that cause the exception

 None
Source code in pyben\exceptions.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class DecodeError(Exception):
    """
    Error occured during decode process.

    Raised when attempting to decode an incompatible bytearray.
    Mostly it indicates the object is a hash digest and should remian
    as a bytes object.

    Parameters
    ----------
    val : None
        Value that cause the exception
    """

    def __init__(self, val=None):
        """Construct Exception DecodeError."""
        msg = f"Unable to decode invalid {type(val)} type = {str(val)}"
        super().__init__(msg)

__init__(val=None)

Construct Exception DecodeError.

Source code in pyben\exceptions.py 
31
32
33
34
def __init__(self, val=None):
    """Construct Exception DecodeError."""
    msg = f"Unable to decode invalid {type(val)} type = {str(val)}"
    super().__init__(msg)

EncodeError

Bases: Exception

Error occured during encoding process.

Raised when attempting to bencode encode an incompatible data type into bencode format. Bencode accepts lists, dicts, strings, integers, and bytes.

Parameters:

Name Type Description Default
val None

Value that cause the exception

 None
Source code in pyben\exceptions.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class EncodeError(Exception):
    """
    Error occured during encoding process.

    Raised when attempting to bencode encode an incompatible
    data type into bencode format. Bencode accepts lists, dicts,
    strings, integers, and bytes.

    Parameters
    ----------
    val : None
        Value that cause the exception
    """

    def __init__(self, val=None):
        """Construct Exception EncodeError."""
        msg = f"Encoder is unable to interpret {type(val)} type = {str(val)}"
        super().__init__(msg)

__init__(val=None)

Construct Exception EncodeError.

Source code in pyben\exceptions.py 
51
52
53
54
def __init__(self, val=None):
    """Construct Exception EncodeError."""
    msg = f"Encoder is unable to interpret {type(val)} type = {str(val)}"
    super().__init__(msg)

FilePathError

Bases: Exception

Bad path error.

Generally raised when the file at the path specified does not exist.

Parameters:

Name Type Description Default
obj None

Value that cause the exception

 None
Source code in pyben\exceptions.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class FilePathError(Exception):
    """Bad path error.

    Generally raised when the file at the path specified
    does not exist.

    Parameters
    ----------
    obj : None
        Value that cause the exception
    """

    def __init__(self, obj=None):
        """Construct Exception Subclass FilePathError."""
        msg = f"{str(obj)} doesn't exist or is unavailable."
        super().__init__(msg)

__init__(obj=None)

Construct Exception Subclass FilePathError.

Source code in pyben\exceptions.py 
69
70
71
72
def __init__(self, obj=None):
    """Construct Exception Subclass FilePathError."""
    msg = f"{str(obj)} doesn't exist or is unavailable."
    super().__init__(msg)