README.rst
1bencode.py
2==========
3
4.. image:: https://img.shields.io/pypi/v/bencode.py.svg?style=flat-square
5 :target: https://pypi.python.org/pypi/bencode.py
6
7.. image:: https://img.shields.io/travis/fuzeman/bencode.py.svg?style=flat-square
8 :target: https://travis-ci.org/fuzeman/bencode.py
9
10.. image:: https://img.shields.io/coveralls/fuzeman/bencode.py/master.svg?style=flat-square
11 :target: https://coveralls.io/github/fuzeman/bencode.py
12
13Simple bencode parser (for Python 2, Python 3 and PyPy), forked from the bencode__ package by Thomas Rampelberg.
14
15__ https://pypi.python.org/pypi/bencode
16
17
18Usage
19-----
20
21**Encode:**
22
23.. code-block:: python
24
25 >>> import bencodepy
26
27 >>> bencodepy.encode({'title': 'Example'})
28 b'd5:title7:Examplee'
29
30 >>> bencodepy.encode(12)
31 b'i12e'
32
33**Decode:**
34
35.. code-block:: python
36
37 >>> import bencodepy
38
39 >>> bencodepy.decode('d5:title7:Examplee')
40 {b'title': b'Example'}
41
42 >>> bencodepy.decode('i12e')
43 12
44
45**Decode to UTF-8:**
46
47.. code-block:: python
48
49 >>> import bencodepy
50
51 >>> bc = bencodepy.Bencode(
52 encoding='utf-8'
53 )
54
55 >>> bc.decode('d5:title7:Examplee')
56 {'title': 'Example'}
57
58:code:`bencode`
59************************************************
60*(legacy, backwards-compatible package)*
61
62This package will continue to be provided for backwards-compatibility, but upgrading to ``bencodepy`` is recommended for more reliable decoding results.
63
64Under-the-hood this just provides proxies to a ``Bencode`` instance created with:
65
66.. code-block:: python
67
68 Bencode(
69 encoding='utf-8',
70 encoding_fallback='value',
71 dict_ordered=True,
72 dict_ordered_sort=True
73 )
74
75**Encode:**
76
77.. code-block:: python
78
79 >>> import bencode
80
81 >>> bencode.encode({'title': 'Example'})
82 'd5:title7:Examplee'
83
84 >>> bencode.encode(12)
85 'i12e'
86
87**Decode:**
88
89.. code-block:: python
90
91 >>> import bencode
92
93 >>> bencode.decode('d5:title7:Examplee')
94 OrderedDict([(u'title', u'Example')])
95
96 >>> bencode.decode('i12e')
97 12
98
99
100API
101---
102
103``bencodepy.Bencode(encoding=None, encoding_fallback=None, dict_ordered=False, dict_ordered_sort=False)``
104
105 Create instance
106
107 - encoding
108 Encoding to decode strings with (or ``None`` for binary)
109 - encoding_fallback
110 Fallback to binary when decoding fails on the specified string types.
111
112 - ``key`` - dictionary keys
113 - ``value`` - values
114 - ``all`` - always fallback to binary
115 - ``None`` - always raise decoding errors
116 - dict_ordered
117 Use ``OrderedDict``
118 - dict_ordered_sort
119 Ensure ``OrderedDict`` is sorted
120
121 Methods:
122
123 - ``decode(value)``
124 Decode bencode string ``value``.
125
126 - ``encode(value)``
127 Encode ``value`` into a bencode string.
128
129 - ``read(fd)``
130 Decode bencode from file or path ``fd``.
131
132 - ``write(data, fd)``
133 Encode ``data`` to file or path ``fd``.
134
135``bencodepy.BencodeDecoder(encoding=None, encoding_fallback=None, dict_ordered=False, dict_ordered_sort=False)``
136
137 Create decoder
138
139 - encoding
140 Encoding to decode strings with (or ``None`` for binary)
141 - encoding_fallback
142 Fallback to binary when decoding fails on the specified string types.
143
144 - ``key`` - dictionary keys
145 - ``value`` - values
146 - ``all`` - always fallback to binary
147 - ``None`` - always raise decoding errors
148 - dict_ordered
149 Use ``OrderedDict``
150 - dict_ordered_sort
151 Ensure ``OrderedDict`` is sorted
152
153 Methods:
154
155 - ``decode(value)``
156 Decode bencode string ``value``.
157
158``bencodepy.BencodeEncoder()``
159
160 Create encoder
161
162 Methods:
163
164 - ``encode(value)``
165 Encode ``value`` into a bencode string.
166
167``bencodepy.bencode(value)``
168
169``bencodepy.encode(value)``
170
171 Encode ``value`` into a bencode string with the default encoder.
172
173``bencodepy.bdecode(value)``
174
175``bencodepy.decode(value)``
176
177 Decode bencode string ``value`` with the default decoder.
178
179``bencodepy.bread(fd)``
180
181 Decode bencode from file or path ``fd`` with the default decoder.
182
183``bencodepy.bwrite(data, fd)``
184
185 Encode ``data`` to file or path ``fd`` with the default encoder.
186
187:code:`bencode`
188************************************************
189
190``bencode.bencode(value)``
191
192``bencode.encode(value)``
193
194 Encode ``value`` into the bencode format.
195
196``bencode.bdecode(value)``
197
198``bencode.decode(value)``
199
200 Decode bencode formatted string ``value``.
201
202``bencode.bread(fd)``
203
204 Read bencode formatted string from file or path ``fd``.
205
206``bencode.bwrite(data, fd)``
207
208 Write ``data`` as a bencode formatted string to file or path ``fd``.
209
