Implemented backwards-compatible bencode package

The library now includes a backwards-compatible `bencode` package, with the updated interface
now available on the `bencodepy` package.

#16

Author: fuzeman

README.rst

@@ -22,30 +22,171 @@ Usage
 
 .. code-block:: python
 
-    import bencode
+    >>> import bencodepy
 
-    bencode.encode({'title': 'Example'})
-    # 'd5:title7:Examplee'
+    >>> bencodepy.encode({'title': 'Example'})
+    b'd5:title7:Examplee'
 
-    bencode.encode(12)
-    # 'i12e'
+    >>> bencodepy.encode(12)
+    b'i12e'
 
 **Decode:**
 
 .. code-block:: python
 
-    import bencode
+    >>> import bencodepy
 
-    bencode.decode('d5:title7:Examplee')
-    # {'title': 'Example'}
+    >>> bencodepy.decode('d5:title7:Examplee')
+    {b'title': b'Example'}
 
-    bencode.decode('i12e')
-    # 12
+    >>> bencodepy.decode('i12e')
+    12
+
+**Decode to UTF-8:**
+
+.. code-block:: python
+
+    >>> import bencodepy
+
+    >>> bc = bencodepy.Bencode(
+        encoding='utf-8'
+    )
+
+    >>> bc.decode('d5:title7:Examplee')
+    {'title': 'Example'}
+
+:code:`bencode`
+************************************************
+*(legacy, backwards-compatible package)*
+
+This package will continue to be provided for backwards-compatibility, but upgrading to ``bencodepy`` is recommended for more reliable decoding results.
+
+Under-the-hood this just provides proxies to a ``Bencode`` instance created with:
+
+.. code-block:: python
+
+    Bencode(
+        encoding='utf-8',
+        encoding_fallback='value',
+        dict_ordered=True,
+        dict_ordered_sort=True
+    )
+
+**Encode:**
+
+.. code-block:: python
+
+    >>> import bencode
+
+    >>> bencode.encode({'title': 'Example'})
+    'd5:title7:Examplee'
+
+    >>> bencode.encode(12)
+    'i12e'
+
+**Decode:**
+
+.. code-block:: python
+
+    >>> import bencode
+
+    >>> bencode.decode('d5:title7:Examplee')
+    OrderedDict([(u'title', u'Example')])
+
+    >>> bencode.decode('i12e')
+    12
 
 
 API
 ---
 
+``bencodepy.Bencode(encoding=None, encoding_fallback=None, dict_ordered=False, dict_ordered_sort=False)``
+
+    Create instance
+
+    - encoding
+       Encoding to decode strings with (or ``None`` for binary)
+    - encoding_fallback
+       Fallback to binary when decoding fails on the specified string types.
+
+       - ``key`` - dictionary keys
+       - ``value`` - values
+       - ``all`` - always fallback to binary
+       - ``None`` - always raise decoding errors
+    - dict_ordered
+       Use ``OrderedDict``
+    - dict_ordered_sort
+       Ensure ``OrderedDict`` is sorted
+
+    Methods:
+
+    - ``decode(value)``
+        Decode bencode string ``value``.
+
+    - ``encode(value)``
+        Encode ``value`` into a bencode string.
+
+    - ``read(fd)``
+        Decode bencode from file or path ``fd``.
+
+    - ``write(data, fd)``
+        Encode ``data`` to file or path ``fd``.
+
+``bencodepy.BencodeDecoder(encoding=None, encoding_fallback=None, dict_ordered=False, dict_ordered_sort=False)``
+
+    Create decoder
+
+    - encoding
+       Encoding to decode strings with (or ``None`` for binary)
+    - encoding_fallback
+       Fallback to binary when decoding fails on the specified string types.
+
+       - ``key`` - dictionary keys
+       - ``value`` - values
+       - ``all`` - always fallback to binary
+       - ``None`` - always raise decoding errors
+    - dict_ordered
+       Use ``OrderedDict``
+    - dict_ordered_sort
+       Ensure ``OrderedDict`` is sorted
+
+    Methods:
+
+    - ``decode(value)``
+        Decode bencode string ``value``.
+
+``bencodepy.BencodeEncoder()``
+
+    Create encoder
+
+    Methods:
+
+    - ``encode(value)``
+        Encode ``value`` into a bencode string.
+
+``bencodepy.bencode(value)``
+
+``bencodepy.encode(value)``
+
+    Encode ``value`` into a bencode string with the default encoder.
+
+``bencodepy.bdecode(value)``
+
+``bencodepy.decode(value)``
+
+    Decode bencode string ``value`` with the default decoder.
+
+``bencodepy.bread(fd)``
+
+    Decode bencode from file or path ``fd`` with the default decoder.
+
+``bencodepy.bwrite(data, fd)``
+
+    Encode ``data`` to file or path ``fd`` with the default encoder.
+
+:code:`bencode`
+************************************************
+
 ``bencode.bencode(value)``
 
 ``bencode.encode(value)``

bencode/BTL.py

@@ -0,0 +1,9 @@
+"""bencode.py - `BTL` backwards compatibility support."""
+
+# Compatibility with previous versions:
+from bencode.exceptions import BencodeDecodeError as BTFailure  # noqa: F401
+
+
+__all__ = (
+    'BTFailure'
+)

bencode/__init__.py

@@ -12,22 +12,14 @@
 
 """bencode.py - bencode encoder + decoder."""
 
-from bencode.common import Bencached
-from bencode.decoder import BencodeDecoder
-from bencode.encoder import BencodeEncoder
+from bencode.BTL import BTFailure
 from bencode.exceptions import BencodeDecodeError
-
-try:
-    import pathlib
-except ImportError:
-    pathlib = None
+from bencodepy import Bencached, Bencode
 
 __all__ = (
+    'BTFailure',
     'Bencached',
-    'Bencode',
-    'BencodeDecoder',
     'BencodeDecodeError',
-    'BencodeEncoder',
     'bencode',
     'bdecode',
     'bread',
@@ -37,87 +29,17 @@
 )
 
 
-class Bencode(object):
-    def __init__(self):
-        self.decoder = BencodeDecoder()
-        self.encoder = BencodeEncoder()
-
-    def decode(self, value):
-        return self.decoder.decode(value)
-
-    def encode(self, value):
-        return self.encoder.encode(value)
-
-
-DEFAULT = Bencode()
-
-
-def bencode(value):
-    # type: (Union[Tuple, List, OrderedDict, Dict, bool, int, str, bytes]) -> bytes
-    """
-    Encode ``value`` into the bencode format.
-
-    :param value: Value
-    :type value: object
-
-    :return: Bencode formatted string
-    :rtype: str
-    """
-    return DEFAULT.encode(value)
-
-
-def bdecode(value):
-    # type: (bytes) -> Union[Tuple, List, OrderedDict, bool, int, str, bytes]
-    """
-    Decode bencode formatted byte string ``value``.
-
-    :param value: Bencode formatted string
-    :type value: bytes
-
-    :return: Decoded value
-    :rtype: object
-    """
-    return DEFAULT.decode(value)
-
-
-def bread(fd):
-    # type: (Union[bytes, str, pathlib.Path, pathlib.PurePath, TextIO, BinaryIO]) -> bytes
-    """Return bdecoded data from filename, file, or file-like object.
-
-    if fd is a bytes/string or pathlib.Path-like object, it is opened and
-    read, otherwise .read() is used. if read() not available, exception
-    raised.
-    """
-    if isinstance(fd, (bytes, str)):
-        with open(fd, 'rb') as fd:
-            return bdecode(fd.read())
-    elif pathlib is not None and isinstance(fd, (pathlib.Path, pathlib.PurePath)):
-        with open(str(fd), 'rb') as fd:
-            return bdecode(fd.read())
-    else:
-        return bdecode(fd.read())
-
-
-def bwrite(data,  # type: Union[Tuple, List, OrderedDict, Dict, bool, int, str, bytes]
-           fd     # type: Union[bytes, str, pathlib.Path, pathlib.PurePath, TextIO, BinaryIO]
-           ):
-    # type: (...) -> None
-    """Write data in bencoded form to filename, file, or file-like object.
-
-    if fd is bytes/string or pathlib.Path-like object, it is opened and
-    written to, otherwise .write() is used. if write() is not available,
-    exception raised.
-    """
-    if isinstance(fd, (bytes, str)):
-        with open(fd, 'wb') as fd:
-            fd.write(bencode(data))
-    elif pathlib is not None and isinstance(fd, (pathlib.Path, pathlib.PurePath)):
-        with open(str(fd), 'wb') as fd:
-            fd.write(bencode(data))
-    else:
-        fd.write(bencode(data))
+DEFAULT = Bencode(
+    encoding='utf-8',
+    encoding_fallback='value',
+    dict_ordered=True,
+    dict_ordered_sort=True
+)
 
+bdecode = DEFAULT.decode
+bencode = DEFAULT.encode
+bread = DEFAULT.read
+bwrite = DEFAULT.write
 
-# Compatibility Proxies
-encode = bencode
 decode = bdecode
+encode = bencode

bencode/exceptions.py

@@ -1,7 +1,6 @@
 """bencode.py - encoder + decode exceptions."""
+from bencodepy.exceptions import BencodeDecodeError
 
-
-class BencodeDecodeError(Exception):
-    """Bencode decode error."""
-
-    pass
+__all__ = (
+    'BencodeDecodeError',
+)