Package: pytest-doctest-custom
DevelopmentLast releasePyPI statusTested on CPython 2.6+/3.2+, PyPy (2, 4 and 5), PyPy3 (2 and 5), PyPy-STM
2.5.1 and Jython 2.7.0, using py.test 2.1+ (2.8.5+ for the CI service; 2.2.4+
for Jython).What does it do?Change the display hook used by doctest to render the object representations.For a given code with doctests, you can run:py.test --doctest-modules --doctest-repr=IPython.lib.pretty:prettyThat will run the doctest examples as usual, but the results won’t be printed
by calling a__repr__method directly, but by calling the given function
with the resulting value as its single parameter.To do that, it just needs a representation formatting callable that given an
object, returns a string with its representation. It should be passed as the--doctest-reprcommand line option addressed asmodule:object, with
dots for nested modules/objects. For built-ins like theasciifunction,
you can just remove themodule:prefix.You can also use a printer callable that always returnsNonebut
writes its result to some stream/file. In this case you should use this
packagestdout_proxy:# mymodule.pyfrompytest_doctest_customimportstdout_proxyfrompprintimportPrettyPrinterpp=PrettyPrinter(width=72,stream=stdout_proxy).pprintSo you can run:py.test --doctest-modules --doctest-repr=mymodule:ppCommon representation formatters/printersBe careful with the default “printers”, you should always use the formatting
methods/functions instead of printing ones, as printer objects commonly
assigns themselves tosys.stdouton initialization and the doctest runner
collects printed data by shortly mocking such stream. This package temporarily
changes thesysoutput/error streams while it finds the addressed
callable, but that’s not enough if the module had already been imported
(likeconftest.py). When possible, use a representation formatter callable
or be explicit about the output stream for the printer callable (it should bepytest_doctest_custom.stdout_proxy).IPython “pretty” module(for output, without the “Out[#]:” prefix)To use this one, you need to have IPython installed on the testing
environment (e.g. includingipythonin the tox deps list). A possible
tox.ini file for running toctests on a project would be:[tox]envlist=py{35,34,27}[testenv]deps=ipythoncommands=py.test {posargs}[pytest]addopts=--doctest-modules--doctest-glob=test_*.rst--doctest-repr=IPython.lib.pretty:pretty--ignore setup.pyYou can customize its parameters such as themax_widthandmax_seq_lengthby creating a custom function for your needs, e.g. by
adding this to theconftest.pymodule and calling py.test with--doctest-repr=conftest:doctest_pretty:# conftest.pyfromIPython.lib.prettyimportprettydefdoctest_pretty(value):returnpretty(value,max_width=72)This pretty printer sorts sets, frozensets and dicts (by keys), breaks lines
with fixed indentation, and has a consistent set/frozenset printing result for
testing on both Python 2 and 3 (CPython 2.7 and 3.3+). But it’s not a Python
standard library, such printer needs IPython as a requirement for running
tests, which comes with much more stuff, not just the pretty printer.
In CPython 2.6/3.2 you need to ensure that the IPython version is compatible
(e.g. withdeps = ipython<2in yourtox.ini).In PyPy that representation printer shows any dict as a dictproxy (tested with
IPython 5.0.0, PyPy 5.3.1) because they’re all the same and the dict printer
gets replaced, so a hack is required to ensure a common behavior between
CPython and PyPy. You can create apytest_configurehook in the very sameconftest.pyeither to monkeypatch totypes.DictProxyTypea dict
derivative liketype("dictproxy",(dict,),{})reloading theIPython.lib.prettymodule afterwards, or to rebuild theIPython.lib.prettydict representation printer by assigning back its_dict_pprinter_factory("{","}",dict)to its_type_pprinters[dict].
The same can be said about PyPy3, and its v2.4.0 is a Python 3.2, therefore it
requiresipython<2.IPython isn’t compatible with Jython.Python “pprint” module(Standard Library)You can use thepprint.pformatfunction directly with--doctest-repr=ppretty:pformat. You shouldn’t directly use thepprintmethod frompprint.PrettyPrinterobjects unless the stream was properly
set tostdout_proxy.To customize its parameters such aswidthandindent, you can put aPrettyPrinterobject in your code, for example:# conftest.pyimportpprintdoctest_pp=pprint.PrettyPrinter(width=72)To run py.test with thepformatattribute of thatPrettyPrinterinstance, giving with--doctest-repr=conftest:doctest_pp.pformatshall be
enough.The standard library pretty printer sorts dicts (by keys), breaks lines with a
custom indentation size, but several containers have a result that depends on
the Python version (e.g. empty set as"set()"in Python 2.6 and 3 but asset([])in Python 2.7, single item set as{item}in Python 3 but asset([item])in Python 2). On the other hand, this is a Python standard
library, there’s no extra requirement for tests, and behaves in PyPy/PyPy3 and
Jython as it does in CPython.InstallingYou can either use pip:pip install pytest-doctest-customOr setup.py directly:python setup.py installCopyright (C) 2016 Danilo de Jesus da Silva Bellini