Metadata-Version: 2.0
Name: pretext
Version: 0.0.1
Summary: Use doctest with bytes, str & unicode on Python 2.x and 3.x
Home-page: https://github.com/moreati/b-prefix-all-the-doctests
Author: Alex Willmer
Author-email: alex@moreati.org.uk
License: Apache Software License 2.0
Keywords: doctest bytes unicode bytestring prefix literal string str
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Testing

pretext
=======

.. image:: https://travis-ci.org/moreati/b-prefix-all-the-doctests.svg
    :target: https://travis-ci.org/moreati/b-prefix-all-the-doctests

This package is an experiment in writing doctests that involve strings,
and that are cross-compatible with Python 2.6, 2.7, and 3.3+.

The problem
-----------

Suppose you have the following doctest

.. code:: python

    >>> textfunc()
    u'I return a textual (unicode) string'

    >>> bytesfunc()
    b'I return a byte (binary) string'

On Python 3.x the first test case will fail, because doctest will compare
``repr(textfunc())`` which will not include a ``u''`` prefix.

On Python 2.x the second test will fail, because ``repr(bytesfunc())`` will
not include the ``b''`` prefix.

If the tests cases are editted to remove the prefixes, i.e.

.. code:: python

    >>> textfunc()
    'I return a textual (unicode) string'

    >>> bytesfunc()
    'I return a byte (binary) string'

then the failures will be reversed. ``textfunc()`` will now fail on Python 2.x,
``bytesfunc()`` will fail on Python 3.x.

The hack
--------

Replace ``repr()`` and ``sys.displayhook`` with versions that always prefix
string literals, regardless of the Python version. Now the doctests can

- directly show the string values returned by functions/methods,
  without resorting to ``print()``, or ``.encode()`` etc
- successfully test the examples on all Python versions 

Proof of concept:

.. code:: python

    r"""
    >>> import sys
    >>> import pretext
    >>> myrepr = bar.PrefixRepr()
    >>> repr = myrepr.repr
    >>> def _displayhook(value):
    ...     if value is not None:
    ...         sys.stdout.write(myrepr.repr(value))
    >>> sys.displayhook = _displayhook
    >>> u''
    u''
    >>> b''
    b''
    >>> bytes()
    b''
    >>> b'\0'
    b'\x00'
    >>> b"'"
    b"'"
    """


Alternatives
------------

If you're ready to run screaming at the above, there are alternatives e.g.

- Wrap byte-string returns in ``bytearray()``.
  ``repr(bytearray(b'abc')) == "bytearray(b'abc'))"`` on all versions of
  python that have ``bytearray()`` (2.6 onward) e.g.

  .. code:: python

       >>> bytearray(bytesfunc())
       bytearray(b'I return a byte (binary) string')

- Support Python 3.x exclusively
- Use ``print(bytesfunc().decode('ascii'))`` and choose your input values carefully
- Use ``#doctest: +SKIP``
- Use ``#doctest: +ELLIPSIS``


