start new version

- hash fields method and parameter allow user customize hash field list
- hash raw parameter allow the output of hash field to be raw bytes
- BEncoder now support encode raw bytes

CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## [0.3.0] - 2018.06.23
+
+### Added
+
+- Add `errors` option in `TorrentFileParser` and `parse_torrent_file` to let user set the encoding error handler. (Thanks [@yasuotakei])
+- Add `-e`/`--error` to CLI option to set the `errors` option of `parse_torrent_file`.
+- `BDecoder` class and `decode` shortcut function to directly decode bytes.
+- `decode` shortcut function to directly encode data to bytes.
+- Added `hash_fields` parameter and method to customize hash field list.
+- Added `hash_raw` parameter to let all hash field be parsed as raw bytes.
+
+### Changed
+
+- **BreakChange** `TorrentFileCreator` rename to `BEncoder` as the origin name don't describe its function.
+- `TorrentFileParser` don't need the outmost level of parsed data to be a `dict` now.
+- `BEncoder` don't need the outmost level of encoded data to be a `dict` now.
+- `BEncoder` now support encode raw bytes.
+
+## [0.2.0] - 2018.5.25
+
+### Change
+
+- Just bump version to 0.2.0 to follow semver.
+
+## [0.1.5rc1] - 2018.4.28
+
+### Added
+
+- `TorrentFileCreator` class and `create_torrent_file` shortcut function for write back data to a torrent file.
+
+## [0.1.4] - 2018-04-06
+
+### Added
+
+- `encoding` option can be `auto`, which will use `chardet` package to decide which encoding to use. If `chardet` is noe installed, will raise a warning and fallback to 'utf-8'. (Thanks to [@ltfychrise])
+- Add changelog.
+
+### Change
+
+- Reorganize test codes/files.
+
+### Fixed
+
+- Fix integer filed can't be negative bug. (Thanks to [@ltfychrise])
+- Fix `_seek_back` method not make `_pos` back bug. (Thanks to [@ltfychrise])
+
+## [0.1.3] - 2017-06-21
+
+### Added
+
+- Now `UnicodeDecodeError` is wrapped in `InvalidTorrentDataException`.
+
+### Fixed
+
+- Use `IOError` instead of `FileNotFoundError` in Python 2.
+
+### Changed
+
+- `InvalidTorrentFileException` rename to `InvalidTorrentDataException`.
+
+## [0.1.2] - 2017-06-21
+
+### Changed
+
+- Emm, I don't know, I just changed the version code...
+
+## [0.1.1] - 2017-06-20
+
+### Added
+
+- CLI add coding `--coding/-c` option for file string filed encoding.
+
+### Changed
+
+- `ed2k` and `filehash` field now use same structure as 'pieces'.
+
+## [0.1.0] - 2017-05-23
+
+### Added
+
+- Parse torrent from file and data into a dict.
+- CLI provided.
+- Simple tests.
+- Available on pip.
+
+[@ltfychrise]: https://github.com/ltfychrise
+[@yasuotakei]: https://github.com/yasuotakei
+[Unreleased]: https://github.com/7sDream/torrent_parser/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/7sDream/torrent_parser/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/7sDream/torrent_parser/compare/v0.1.5rc1...v0.2.0
+[0.1.5rc1]: https://github.com/7sDream/torrent_parser/compare/v0.1.4...v0.1.5rc1
+[0.1.4]: https://github.com/7sDream/torrent_parser/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/7sDream/torrent_parser/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/7sDream/torrent_parser/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/7sDream/torrent_parser/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/7sDream/torrent_parser/tree/v0.1.0

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 7sDream
+Copyright (c) 2017 - 2018 7sDream
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MANIFEST.in

@@ -1,3 +1 @@
-include README.md LICENSE changelog.md
-include test.py
-include test.torrent
+include README.md LICENSE CHANGELOG.md

README.md

@@ -1,4 +1,16 @@
-# Torrent file parser for Python
+# Torrent file parser and creator for Python
+
+A simple parser for `.torrent` file.
+
+Can also edit and write back to torrent format after version 0.2.0.
+
+## Features
+
+- Decoder and encoder for torrent files
+- Auto decode bytes field to string with used specified encoding and error handler
+- Auto detect encoding when use `auto` as encoding(need `chardet` installed)
+- Auto decode hash value filed to hash blocks, also customizable
+- CLI provided, with JSON output
 
 ## Install
 
@@ -30,16 +42,33 @@ $ cat test.torrent | pytp
 ```pycon
 >>> import torrent_parser as tp
 >>> data = tp.parse_torrent_file('test.torrent')
->>> print(data['announce'])
+>>> data['announce']
 http://tracker.trackerfix.com:80/announce
+>>> data['announce'] = 'http://127.0.0.1:12345'
+>>> tp.create_torrent_file('new.torrent', data)
+```
+
+or you don't operate with file, just raw bytes:
+
+```pycon
+>>> import torrent_parser as tp
+>>> data = tp.decode(b'd3:negi-1ee')
+>>> data['neg']
+-1
+>>> tp.encode(data)
+b'd3:negi-1ee'
 ```
 
 ## Test
 
 ```bash
-python -m unittest test
+python -m unittest tests
 ```
 
+## Changelog
+
+See [Changelog][CHANGELOG].
+
 ## LICENSE
 
 See [License][LICENSE].
@@ -48,3 +77,4 @@ See [License][LICENSE].
 [screenshots-normal]: http://rikka-10066868.image.myqcloud.com/1492616d-9f14-4fe2-9146-9a3ac06c6868.png
 [screenshots-indent]: http://rikka-10066868.image.myqcloud.com/eadc4184-6deb-42eb-bfd4-239da8f50c08.png
 [LICENSE]: https://github.com/7sDream/torrent_parser/blob/master/LICENSE
+[CHANGELOG]: https://github.com/7sDream/torrent_parser/blob/master/CHANGELOG.md

setup.py

@@ -17,7 +17,7 @@ setup(
     license='MIT',
     author='7sDream',
     author_email='7seconddream@gmail.com',
-    description='A .torrent file parser for both Python 2 and 3',
+    description='A .torrent file parser and creator for both Python 2 and 3',
     install_requires=[],
     entry_points={
         'console_scripts': ['pytp=torrent_parser:__main']

tests/__init__.py

@@ -0,0 +1,7 @@
+from .test_create import *
+from .test_parse import *
+from .test_encoding_error import *
+from .test_encode import *
+from .test_decode import *
+from .test_hash_field import *
+from .test_hash_raw import *

tests/test_create.py

@@ -0,0 +1,35 @@
+from __future__ import unicode_literals
+
+import collections
+import hashlib
+import io
+import os.path
+import unittest
+
+from torrent_parser import TorrentFileParser, BEncoder
+
+
+class TestCreate(unittest.TestCase):
+    TEST_FILES_DIR = os.path.join(os.path.dirname(__file__), 'test_files')
+    REAL_FILE = os.path.join(TEST_FILES_DIR, 'real.torrent')
+
+    def test_simple_create(self):
+        data = collections.OrderedDict()
+        data['a'] = 1
+        data['b'] = 2
+        self.assertEqual(BEncoder(data).encode(), b'd1:ai1e1:bi2ee')
+
+    def test_same_output_if_no_edit(self):
+        with open(self.REAL_FILE, 'rb') as fp:
+            in_data = fp.read()
+            data = TorrentFileParser(io.BytesIO(in_data), True).parse()
+            out_data = BEncoder(data).encode()
+            m1 = hashlib.md5()
+            m1.update(in_data)
+            m2 = hashlib.md5()
+            m2.update(out_data)
+            self.assertEqual(m1.digest(), m2.digest())
+
+    def test_dont_need_dict_outmost(self):
+        data = 123456
+        self.assertEqual(BEncoder(data).encode(), b'i123456e')

tests/test_decode.py

@@ -0,0 +1,11 @@
+from __future__ import unicode_literals
+
+import unittest
+
+from torrent_parser import decode
+
+
+class TestDecode(unittest.TestCase):
+
+    def test_decode(self):
+        self.assertEqual(decode(b'i12345e'), 12345)

tests/test_encode.py

@@ -0,0 +1,11 @@
+from __future__ import unicode_literals
+
+import unittest
+
+from torrent_parser import encode
+
+
+class TestEncode(unittest.TestCase):
+
+    def test_encode(self):
+        self.assertEqual(encode(12345), b'i12345e')

tests/test_encoding_error.py

@@ -0,0 +1,25 @@
+from __future__ import unicode_literals
+
+import os.path
+import unittest
+
+from torrent_parser import (
+    TorrentFileParser, parse_torrent_file, InvalidTorrentDataException
+)
+
+
+class TestDecodingError(unittest.TestCase):
+    TEST_FILES_DIR = os.path.join(os.path.dirname(__file__), 'test_files')
+    FILE = os.path.join(TEST_FILES_DIR, 'utf8.encoding.error.torrent')
+
+    def test_default_option_will_raise_exception(self):
+        with self.assertRaises(InvalidTorrentDataException):
+            parse_torrent_file(self.FILE)
+        with self.assertRaises(InvalidTorrentDataException):
+            with open(self.FILE, 'rb') as f:
+                TorrentFileParser(f).parse()
+
+    def test_not_raise_exception_when_use_ignore(self):
+        parse_torrent_file(self.FILE, errors='ignore')
+        with open(self.FILE, 'rb') as f:
+            TorrentFileParser(f, errors='ignore').parse()

tests/test_files/neg.torrent

@@ -0,0 +1 @@
+d3:negi-1ee

tests/test_files/outmost.string.torrent

@@ -0,0 +1 @@
+8:announce

tests/test_hash_field.py

@@ -0,0 +1,21 @@
+from __future__ import unicode_literals
+
+import os.path
+import unittest
+
+from torrent_parser import (
+    TorrentFileParser, parse_torrent_file, decode
+)
+
+
+class TestHashField(unittest.TestCase):
+    TEST_FILES_DIR = os.path.join(os.path.dirname(__file__), 'test_files')
+    FILE = os.path.join(TEST_FILES_DIR, 'utf8.encoding.error.torrent')
+
+    def test_not_raise_exception_when_add_hash_fields(self):
+        parse_torrent_file(self.FILE, hash_fields={'info_hash': (20, False)})
+        with open(self.FILE, 'rb') as f:
+            TorrentFileParser(f).hash_field('info_hash').parse()
+        with open(self.FILE, 'rb') as f:
+            data = f.read()
+            decode(data, hash_fields={'info_hash': (20, False)})

tests/test_hash_raw.py

@@ -0,0 +1,23 @@
+from __future__ import unicode_literals
+
+import os.path
+import unittest
+
+from torrent_parser import decode, encode
+
+
+class TestHashRaw(unittest.TestCase):
+    TEST_FILES_DIR = os.path.join(os.path.dirname(__file__), 'test_files')
+    FILE = os.path.join(TEST_FILES_DIR, 'utf8.encoding.error.torrent')
+
+    def test_hash_raw_decode(self):
+        data = b'd4:hash4:\xAA\xBB\xCC\xDDe'
+        res = decode(data, hash_fields={'hash': (4, False)}, hash_raw=False)
+        self.assertEqual(res['hash'], 'aabbccdd')
+        res = decode(data, hash_fields={'hash': (4, False)}, hash_raw=True)
+        self.assertEqual(res['hash'], b'\xAA\xBB\xCC\xDD')
+
+    def test_raw_bytes_encode(self):
+        res = {'hash': b'\xAA\xBB\xCC\xDD'}
+        data = encode(res)
+        self.assertEqual(data, b'd4:hash4:\xAA\xBB\xCC\xDDe')

tests/test_parse.py

@@ -1,37 +1,45 @@
 from __future__ import unicode_literals
 
-import unittest
 import collections
+import os.path
+import unittest
 
 from torrent_parser import TorrentFileParser, parse_torrent_file
 
 
-class Test(unittest.TestCase):
-    TEST_FILENAME = 'test.torrent'
+class TestParse(unittest.TestCase):
+    TEST_FILES_DIR = os.path.join(os.path.dirname(__file__), 'test_files')
+    REAL_FILE = os.path.join(TEST_FILES_DIR, 'real.torrent')
+    NEG_FILE = os.path.join(TEST_FILES_DIR, 'neg.torrent')
+    STRING_FILE = os.path.join(TEST_FILES_DIR, 'outmost.string.torrent')
 
     def test_parse_torrent_file_use_shortcut(self):
-        parse_torrent_file(self.TEST_FILENAME)
+        parse_torrent_file(self.REAL_FILE)
 
     def test_parse_torrent_file_use_class(self):
-        with open(self.TEST_FILENAME, 'rb') as fp:
+        with open(self.REAL_FILE, 'rb') as fp:
             TorrentFileParser(fp).parse()
 
+    def test_encoding_auto(self):
+        with open(self.REAL_FILE, 'rb') as fp:
+            TorrentFileParser(fp, encoding='auto').parse()
+
     def test_parse_torrent_file_to_ordered_dict(self):
-        data = parse_torrent_file(self.TEST_FILENAME, True)
+        data = parse_torrent_file(self.REAL_FILE, True)
         self.assertIsInstance(data, collections.OrderedDict)
 
-        with open(self.TEST_FILENAME, 'rb') as fp:
+        with open(self.REAL_FILE, 'rb') as fp:
             data = TorrentFileParser(fp, True).parse()
         self.assertIsInstance(data, collections.OrderedDict)
 
     def test_parse_correctness(self):
-        data = parse_torrent_file(self.TEST_FILENAME)
+        data = parse_torrent_file(self.REAL_FILE)
         self.assertIn(['udp://tracker.publicbt.com:80/announce'],
                       data['announce-list'])
         self.assertEqual(data['creation date'], 1409254242)
 
     def test_parse_two_times(self):
-        with open(self.TEST_FILENAME, 'rb') as fp:
+        with open(self.REAL_FILE, 'rb') as fp:
             parser = TorrentFileParser(fp)
             data = parser.parse()
             self.assertIn(['udp://tracker.publicbt.com:80/announce'],
@@ -41,3 +49,15 @@ class Test(unittest.TestCase):
             self.assertIn(['udp://tracker.publicbt.com:80/announce'],
                           data['announce-list'])
             self.assertEqual(data['creation date'], 1409254242)
+
+    def test_int_is_negative(self):
+        data = parse_torrent_file(self.NEG_FILE)
+        self.assertEqual(data['neg'], -1)
+
+    def test_dont_need_dict_outmost(self):
+        data = parse_torrent_file(self.STRING_FILE)
+        self.assertEqual(data, 'announce')
+
+
+if __name__ == '__main__':
+    unittest.main()

torrent_parser.py

@@ -12,30 +12,96 @@ Usage:
 
     with open(filename, 'rb') as f: # the binary mode 'b' is necessary
         data = TorrentFileParser(f).parse()
+
+    # then you can edit the data
+
+    data['announce-list'].append(['http://127.0.0.1:8080'])
+
+    # and create a new torrent file from data
+
+    create_torrent_file('new.torrent', data)
+
+    # or
+
+    with open('new.torrent', 'wb') as f:
+        f.write(TorrentFileCreator(data).encode())
+
+    # or you don't deal with file, just object in memory
+
+    data = decode(b'i12345e') # data = 12345
+    content = encode(data) # content = b'i12345e'
+
 """
 
 from __future__ import print_function, unicode_literals
 
 import argparse
+import binascii
 import collections
 import io
 import json
 import sys
+import warnings
 
+try:
+    FileNotFoundError
+except NameError:
+    # Python 2 do not have FileNotFoundError, use IOError instead
+    # noinspection PyShadowingBuiltins
+    FileNotFoundError = IOError
+
+try:
+    # noinspection PyPackageRequirements
+    from chardet import detect as _detect
+except ImportError:
+    def _detect(_):
+        warnings.warn("No chardet module installed, encoding will be utf-8")
+        return {'encoding': 'utf-8', 'confidence': 1}
+
+try:
+    # noinspection PyUnresolvedReferences
+    # For Python 2
+    str_type = unicode
+except NameError:
+    # For Python 3
+    str_type = str
 
 __all__ = [
-    'InvalidTorrentFileException',
-    'parse_torrent_file',
+    'InvalidTorrentDataException',
+    'BEncoder',
+    'BDecoder',
+    'encode',
+    'decode',
     'TorrentFileParser',
+    'create_torrent_file',
+    'parse_torrent_file',
 ]
 
-__version__ = '0.1.1'
+__version__ = '0.3.0'
 
 
-class InvalidTorrentFileException(Exception):
+def detect(content):
+    return _detect(content)['encoding']
+
+
+class InvalidTorrentDataException(Exception):
     def __init__(self, pos, msg=None):
-        msg = msg or "Invalid torrent format when reading at pos " + str(pos)
-        super(InvalidTorrentFileException, self).__init__(msg)
+        msg = msg or "Invalid torrent format when read at pos {pos}"
+        msg = msg.format(pos=pos)
+        super(InvalidTorrentDataException, self).__init__(msg)
+
+
+class __EndCls(object):
+    pass
+
+
+_END = __EndCls()
+
+
+def _check_hash_field_params(name, value):
+    return isinstance(name, str_type) \
+           and isinstance(value, tuple) and len(value) == 2 \
+           and isinstance(value[0], int) and isinstance(value[1], bool)
 
 
 class TorrentFileParser(object):
@@ -51,6 +117,14 @@ class TorrentFileParser(object):
     INT_INDICATOR = b'i'
     END_INDICATOR = b'e'
     STRING_INDICATOR = b''
+    STRING_DELIMITER = b':'
+
+    HASH_FIELD_PARAMS = {
+        # field length need_list
+        'pieces': (20, True),
+        'ed2k': (16, False),
+        'filehash': (20, False),
+    }
 
     TYPES = [
         (TYPE_LIST, LIST_INDICATOR),
@@ -60,44 +134,82 @@ class TorrentFileParser(object):
         (TYPE_STRING, STRING_INDICATOR),
     ]
 
-    def __init__(self, fp, use_ordered_dict=False, encoding='utf-8'):
+    def __init__(
+            self, fp, use_ordered_dict=False, encoding='utf-8', errors='strict',
+            hash_fields=None, hash_raw=False,
+    ):
         """
         :param fp: a **binary** file-like object to parse,
           which means need 'b' mode when use built-in open function
-        :param encoding: file content encoding, default utf-8
-        :param use_ordered_dict: Use collections.OrderedDict as dict container
-          default False, which mean use built-in dict
+        :param bool use_ordered_dict: Use collections.OrderedDict as dict
+          container default False, which mean use built-in dict
+        :param str encoding: file content encoding, default utf-8, use 'auto'
+          to enable charset auto detection (need 'chardet' package installed)
+        :param str errors: how to deal with encoding error when try to parse
+          string from content with ``encoding``
+        :param Dict[str, Tuple[int, bool]] hash_fields: extra fields should
+          be treated as hash value. dict key is the field name, value is a
+          two-element tuple of (hash_block_length, as_a_list).
+          See :any:`hash_field` for detail
         """
         if getattr(fp, 'read', ) is None \
                 or getattr(fp, 'seek') is None:
-            raise ValueError('Argument fp needs a file like object')
+            raise ValueError('Parameter fp needs a file like object')
 
         self._pos = 0
         self._encoding = encoding
         self._content = fp
         self._use_ordered_dict = use_ordered_dict
+        self._error_handler = errors
+        self._hash_fields = dict(TorrentFileParser.HASH_FIELD_PARAMS)
+        if hash_fields is not None:
+            for k, v in hash_fields.items():
+                if _check_hash_field_params(k, v):
+                    self._hash_fields[k] = v
+                else:
+                    raise ValueError(
+                        "Invalid hash field parameter, it should be type of "
+                        "Dict[str, Tuple[int, bool]]"
+                    )
+        self._hash_raw = bool(hash_raw)
+
+    def hash_field(self, name, block_length=20, need_list=False):
+        """
+        Let field with the `name` to be treated as hash value, don't decode it
+        as a string.
+
+        :param str name: field name
+        :param int block_length: hash block length for split
+        :param bool need_list:  if True, when the field only has one block(
+          or even empty) its parse result will be a one-element list(
+          or empty list); If False, will be a string in 0 or 1 block condition
+        :return: return self, so you can chained call
+        """
+        v = (block_length, need_list)
+        if _check_hash_field_params(name, v):
+            self._hash_fields[name] = v
+        else:
+            raise ValueError("Invalid hash field parameter")
+        return self
 
     def parse(self):
         """
-        :return: the parse result
-        :type: depends on ``use_ordered_dict`` option when init the parser
-          see :any:`TorrentFileParser.__init__`
+        :rtype: dict|list|int|str|bytes
+        :raise: :any:`InvalidTorrentDataException` when parse failed or error
+          happened when decode string using specified encoding
         """
         self._restart()
         data = self._next_element()
 
         try:
             c = self._read_byte(1, True)
-            raise InvalidTorrentFileException(
+            raise InvalidTorrentDataException(
                 0, 'Expect EOF, but get [{}] at pos {}'.format(c, self._pos)
             )
         except EOFError:  # expect EOF
             pass
 
-        if isinstance(data, dict):
-            return data
-
-        raise InvalidTorrentFileException('Outermost element is not a dict')
+        return data
 
     def _read_byte(self, count=1, raise_eof=False):
         assert count >= 0
@@ -105,7 +217,7 @@ class TorrentFileParser(object):
         if count != 0 and len(gotten) == 0:
             if raise_eof:
                 raise EOFError()
-            raise InvalidTorrentFileException(
+            raise InvalidTorrentDataException(
                 self._pos,
                 'Unexpected EOF when reading torrent file'
             )
@@ -114,6 +226,7 @@ class TorrentFileParser(object):
 
     def _seek_back(self, count):
         self._content.seek(-count, 1)
+        self._pos = self._pos - count
 
     def _restart(self):
         self._content.seek(0, 0)
@@ -121,18 +234,17 @@ class TorrentFileParser(object):
 
     def _dict_items_generator(self):
         while True:
-            try:
-                k = self._next_element()
-            except InvalidTorrentFileException:
+            k = self._next_element()
+            if k is _END:
                 return
-            if k == 'pieces':
-                v = self._next_hash()
-            elif k == 'ed2k':
-                v = self._next_hash(16, False)
-            elif k == 'filehash':
-                v = self._next_hash(20, False)
+            if not isinstance(k, str_type):
+                raise InvalidTorrentDataException(
+                    self._pos, "Type of dict key can't be " + type(k).__name__
+                )
+            if k in self._hash_fields:
+                v = self._next_hash(*self._hash_fields[k])
             else:
-                v = self._next_element()
+                v = self._next_element(k)
             if k == 'encoding':
                 self._encoding = v
             yield k, v
@@ -145,9 +257,8 @@ class TorrentFileParser(object):
 
     def _list_items_generator(self):
         while True:
-            try:
-                element = self._next_element()
-            except InvalidTorrentFileException:
+            element = self._next_element()
+            if element is _END:
                 return
             yield element
 
@@ -157,33 +268,57 @@ class TorrentFileParser(object):
     def _next_int(self, end=END_INDICATOR):
         value = 0
         char = self._read_byte(1)
+        neg = False
         while char != end:
-            # noinspection PyTypeChecker
-            if not b'0' <= char <= b'9':
-                raise InvalidTorrentFileException(self._pos)
-            value = value * 10 + int(char) - int(b'0')
+            if not neg and char == b'-':
+                neg = True
+            elif not b'0' <= char <= b'9':
+                raise InvalidTorrentDataException(self._pos - 1)
+            else:
+                value = value * 10 + int(char) - int(b'0')
             char = self._read_byte(1)
-        return value
+        return -value if neg else value
 
-    def _next_string(self, decode=True):
-        length = self._next_int(b':')
+    def _next_string(self, need_decode=True, field=None):
+        length = self._next_int(self.STRING_DELIMITER)
         raw = self._read_byte(length)
-        if decode:
-            string = raw.decode(self._encoding)
+        if need_decode:
+            encoding = self._encoding
+            if encoding == 'auto':
+                self.encoding = encoding = detect(raw)
+            try:
+                string = raw.decode(encoding, self._error_handler)
+            except UnicodeDecodeError as e:
+                msg = [
+                    "Fail to decode string at pos {pos} using encoding ",
+                    e.encoding
+                ]
+                if field:
+                    msg.extend([
+                        ' when parser field "', field, '"'
+                        ', maybe it is an hash field. ',
+                        'You can use self.hash_field("', field, '") ',
+                        'to let it be treated as hash value, ',
+                        'so this error may disappear'
+                    ])
+                raise InvalidTorrentDataException(
+                    self._pos - length + e.start,
+                    ''.join(msg)
+                )
             return string
         return raw
 
-    @staticmethod
-    def __to_hex(v):
-        return hex(ord(v) if isinstance(v, str) else v)[2:].rjust(2, str(0))
-
-    def _next_hash(self, p_len=20, need_list=True):
-        raw = self._next_string(decode=False)
+    def _next_hash(self, p_len, need_list):
+        raw = self._next_string(need_decode=False)
         if len(raw) % p_len != 0:
-            raise InvalidTorrentFileException(self._pos)
+            raise InvalidTorrentDataException(
+                self._pos - len(raw), "Hash bit length not match at pos {pos}"
+            )
+        if self._hash_raw:
+            return raw
         res = [
-            ''.join([self.__to_hex(c) for c in h])
-            for h in (raw[x:x+p_len] for x in range(0, len(raw), p_len))
+            binascii.hexlify(chunk).decode('ascii')
+            for chunk in (raw[x:x+p_len] for x in range(0, len(raw), p_len))
         ]
         if len(res) == 0 and not need_list:
             return ''
@@ -191,8 +326,9 @@ class TorrentFileParser(object):
             return res[0]
         return res
 
-    def _next_end(self):
-        raise InvalidTorrentFileException(self._pos)
+    @staticmethod
+    def _next_end():
+        return _END
 
     def _next_type(self):
         for (element_type, indicator) in self.TYPES:
@@ -201,28 +337,258 @@ class TorrentFileParser(object):
             if indicator == char:
                 return element_type
             self._seek_back(indicator_length)
-        raise InvalidTorrentFileException(self._pos)
+        raise InvalidTorrentDataException(self._pos)
 
     def _type_to_func(self, t):
         return getattr(self, '_next_' + t)
 
-    def _next_element(self):
+    def _next_element(self, field=None):
         element_type = self._next_type()
-        element = self._type_to_func(element_type)()
+        if element_type is TorrentFileParser.TYPE_STRING and field is not None:
+            element = self._type_to_func(element_type)(field=field)
+        else:
+            element = self._type_to_func(element_type)()
         return element
 
 
-def parse_torrent_file(filename, use_ordered_dict=False):
-    """
-    Shortcut function for parse torrent object use TorrentFileParser
+class BEncoder(object):
 
-    :param string filename: torrent filename
-    :param bool use_ordered_dict: see :any:`TorrentFileParser.__init__`
-    :rtype: dict if ``use_ordered_dict`` is false,
-      collections.OrderedDict otherwise
+    TYPES = {
+        (dict,): TorrentFileParser.TYPE_DICT,
+        (list,): TorrentFileParser.TYPE_LIST,
+        (int,): TorrentFileParser.TYPE_INT,
+        (str_type, bytes): TorrentFileParser.TYPE_STRING,
+    }
+
+    def __init__(self, data, encoding='utf-8', hash_fields=None):
+        """
+        :param dict|list|int|str data: data will be encoded
+        :param str encoding: string field output encoding
+        :param List[str] hash_fields: see
+          :any:`TorrentFileParser.__init__`
+        """
+        self._data = data
+        self._encoding = encoding
+        self._hash_fields = list(TorrentFileParser.HASH_FIELD_PARAMS.keys())
+        if hash_fields is not None:
+            self._hash_fields.extend(str_type(hash_fields))
+
+    def hash_field(self, name):
+        """
+        see :any:`TorrentFileParser.hash_field`
+
+        :param str name:
+        :return: return self, so you can chained call
+        """
+        return self._hash_fields.append(str_type(name))
+
+    def encode(self):
+        """
+        Encode to bytes
+
+        :rtype: bytes
+        """
+        return b''.join(self._output_element(self._data))
+
+    def encode_to_filelike(self):
+        """
+        Encode to a file-like(BytesIO) object
+
+        :rtype: BytesIO
+        """
+        return io.BytesIO(self.encode())
+
+    def _output_string(self, data):
+        if isinstance(data, str_type):
+            data = data.encode(self._encoding)
+        yield str(len(data)).encode('ascii')
+        yield TorrentFileParser.STRING_DELIMITER
+        yield data
+
+    @staticmethod
+    def _output_int(data):
+        yield TorrentFileParser.INT_INDICATOR
+        yield str(data).encode('ascii')
+        yield TorrentFileParser.END_INDICATOR
+
+    def _output_decode_hash(self, data):
+        if isinstance(data, str_type):
+            data = [data]
+        result = []
+        for hash_line in data:
+            if not isinstance(hash_line, str_type):
+                raise InvalidTorrentDataException(
+                    None,
+                    "Hash must be " + str_type.__name__ + " not " +
+                    type(hash_line).__name__,
+                )
+            if len(hash_line) % 2 != 0:
+                raise InvalidTorrentDataException(
+                    None,
+                    "Hash(" + hash_line + ") length(" + str(len(hash_line)) +
+                    ") is a not even number",
+                )
+            try:
+                raw = binascii.unhexlify(hash_line)
+            except binascii.Error as e:
+                raise InvalidTorrentDataException(
+                    None, str(e),
+                )
+            result.append(raw)
+        for x in self._output_string(b''.join(result)):
+            yield x
+
+    def _output_dict(self, data):
+        yield TorrentFileParser.DICT_INDICATOR
+        for k, v in data.items():
+            if not isinstance(k, str_type):
+                raise InvalidTorrentDataException(
+                    None, "Dict key must be " + str_type.__name__,
+                )
+            for x in self._output_element(k):
+                yield x
+            if k in self._hash_fields:
+                for x in self._output_decode_hash(v):
+                    yield x
+            else:
+                for x in self._output_element(v):
+                    yield x
+        yield TorrentFileParser.END_INDICATOR
+
+    def _output_list(self, data):
+        yield TorrentFileParser.LIST_INDICATOR
+        for v in data:
+            for x in self._output_element(v):
+                yield x
+        yield TorrentFileParser.END_INDICATOR
+
+    def _type_to_func(self, t):
+        return getattr(self, '_output_' + t)
+
+    def _output_element(self, data):
+        for types, t in self.TYPES.items():
+            if isinstance(data, types):
+                # noinspection PyCallingNonCallable
+                return self._type_to_func(t)(data)
+        raise InvalidTorrentDataException(
+            None,
+            "Invalid type for torrent file: " + type(data).__name__,
+        )
+
+
+class BDecoder(object):
+    def __init__(
+        self, data, use_ordered_dict=False, encoding='utf-8', errors='strict',
+        hash_fields=None, hash_raw=False,
+    ):
+        """
+        See :any:`TorrentFileParser.__init__` for parameter description.
+
+        :param bytes data: raw data to be decoded
+        :param bool use_ordered_dict:
+        :param str encoding:
+        :param str errors:
+        :param Dict[str, Tuple[int, bool]] hash_fields:
+        :param bool hash_raw:
+        """
+        self._parser = TorrentFileParser(
+            io.BytesIO(bytes(data)),
+            use_ordered_dict,
+            encoding,
+            errors,
+            hash_fields,
+            hash_raw,
+        )
+
+    def hash_field(self, name, block_length=20, need_dict=False):
+        """
+        See :any:`TorrentFileParser.hash_field` for parameter description
+
+        :param name:
+        :param block_length:
+        :param need_dict:
+        :return: return self, so you can chained call
+        """
+        self._parser.hash_field(name, block_length, need_dict)
+        return self
+
+    def decode(self):
+        return self._parser.parse()
+
+
+def encode(data, encoding='utf-8', hash_fields=None):
+    """
+    Shortcut function for encode python object to torrent file format(bencode)
+
+    See :any:`BEncoder.__init__` for parameter description
+
+    :param dict|list|int|str|bytes data: data to be encoded
+    :param str encoding:
+    :param List[str] hash_fields:
+    :rtype: bytes
+    """
+    return BEncoder(data, encoding, hash_fields).encode()
+
+
+def decode(
+        data, use_ordered_dict=False, encoding='utf-8', errors='strict',
+        hash_fields=None, hash_raw=False,
+):
+    """
+    Shortcut function for decode bytes as torrent file format(bencode) to python
+    object
+
+    See :any:`BDecoder.__init__` for parameter description
+
+    :param bytes data: raw data to be decoded
+    :param bool use_ordered_dict:
+    :param str encoding:
+    :param str errors:
+    :param Dict[str, Tuple[int, bool]] hash_fields:
+    :param bool hash_raw:
+    :rtype: dict|list|int|str|bytes|bytes
+    """
+    return BDecoder(
+        data, use_ordered_dict, encoding, errors, hash_fields, hash_raw,
+    ).decode()
+
+
+def parse_torrent_file(
+        filename, use_ordered_dict=False, encoding='utf-8', errors='strict',
+        hash_fields=None, hash_raw=False,
+):
+    """
+    Shortcut function for parse torrent object using TorrentFileParser
+
+    See :any:`TorrentFileParser.__init__` for parameter description
+
+    :param str filename: torrent filename
+    :param bool use_ordered_dict:
+    :param str encoding:
+    :param str errors:
+    :param Dict[str, Tuple[int, bool]] hash_fields:
+    :param bool hash_raw:
+    :rtype: dict|list|int|str|bytes
     """
     with open(filename, 'rb') as f:
-        return TorrentFileParser(f, use_ordered_dict).parse()
+        return TorrentFileParser(
+            f, use_ordered_dict, encoding, errors, hash_fields, hash_raw,
+        ).parse()
+
+
+def create_torrent_file(filename, data, encoding='utf-8', hash_fields=None):
+    """
+    Shortcut function for create a torrent file using BEncoder
+
+    see :any:`BDecoder.__init__` for parameter description
+
+    :param str filename: output torrent filename
+    :param dict|list|int|str|bytes data:
+    :param str encoding:
+    :param List[str] hash_fields:
+    """
+    with open(filename, 'wb') as f:
+        f.write(BEncoder(data, encoding, hash_fields).encode())
 
 
 def __main():
@@ -239,7 +605,10 @@ def __main():
                         help='ensure output json use ascii char, '
                              'escape other char use \\u')
     parser.add_argument('--coding', '-c', default='utf-8',
-                        help='string encoding, default utf-8')
+                        help='string encoding, default "utf-8"')
+    parser.add_argument('--errors', '-e', default='strict',
+                        help='decoding error handler, default "strict", you can'
+                             ' use "ignore" or "replace" to avoid exception')
     parser.add_argument('--version', '-v', action='store_true', default=False,
                         help='print version and exit')
     args = parser.parse_args()
@@ -256,11 +625,13 @@ def __main():
         else:
             target_file = open(args.file, 'rb')
     except FileNotFoundError:
-        sys.stderr.write('Unable to find file {}\n'.format(args.file))
+        sys.stderr.write('File "{}" not exist\n'.format(args.file))
         exit(1)
 
     # noinspection PyUnboundLocalVariable
-    data = TorrentFileParser(target_file, not args.dict, args.coding).parse()
+    data = TorrentFileParser(
+        target_file, not args.dict, args.coding, args.errors
+    ).parse()
 
     data = json.dumps(
         data, ensure_ascii=args.ascii,
@@ -269,5 +640,6 @@ def __main():
 
     print(data)
 
+
 if __name__ == '__main__':
     __main()