sphinxext-ip/tests/util.py

228 lines
5.3 KiB
Python
Raw Normal View History

2016-05-01 18:12:02 +02:00
# -*- coding: utf-8 -*-
"""
Sphinx test suite utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import io
import shutil
import sys
import tempfile
from functools import wraps
2016-05-01 18:12:02 +02:00
from path import Path
from sphinx import application
2016-05-01 18:12:02 +02:00
__all__ = [
2021-01-02 06:20:53 +01:00
"test_root",
"raises",
"raises_msg",
"Struct",
"ListOutput",
"SphinxTestApplication",
"with_app",
"gen_with_app",
"Path",
"with_tempdir",
"write_file",
"sprint",
2016-05-01 18:12:02 +02:00
]
2021-01-02 06:20:53 +01:00
test_root = Path(__file__).parent.joinpath("root").abspath()
2016-05-01 18:12:02 +02:00
def _excstr(exc):
if type(exc) is tuple:
return str(tuple(map(_excstr, exc)))
return exc.__name__
2016-05-01 18:12:02 +02:00
def raises(exc, func, *args, **kwds):
"""
Raise :exc:`AssertionError` if ``func(*args, **kwds)`` does not
raise *exc*.
"""
try:
func(*args, **kwds)
except exc:
pass
else:
2021-01-02 06:20:53 +01:00
raise AssertionError("%s did not raise %s" % (func.__name__, _excstr(exc)))
2016-05-01 18:12:02 +02:00
2016-05-01 18:12:02 +02:00
def raises_msg(exc, msg, func, *args, **kwds):
"""
Raise :exc:`AssertionError` if ``func(*args, **kwds)`` does not
raise *exc*, and check if the message contains *msg*.
"""
try:
func(*args, **kwds)
except exc as err:
2021-01-02 06:20:53 +01:00
assert msg in str(err), '"%s" not in "%s"' % (msg, err)
2016-05-01 18:12:02 +02:00
else:
2021-01-02 06:20:53 +01:00
raise AssertionError("%s did not raise %s" % (func.__name__, _excstr(exc)))
2016-05-01 18:12:02 +02:00
class Struct(object):
def __init__(self, **kwds):
self.__dict__.update(kwds)
2016-05-01 18:12:02 +02:00
class ListOutput(object):
"""
File-like object that collects written text in a list.
"""
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
def __init__(self, name):
self.name = name
self.content = []
def reset(self):
del self.content[:]
def write(self, text):
self.content.append(text)
class SphinxTestApplication(application.Sphinx):
2016-05-01 18:12:02 +02:00
"""
A subclass of :class:`Sphinx` that runs on the test root, with some
better default values for the initialization parameters.
"""
2021-01-02 06:20:53 +01:00
def __init__(
self,
srcdir=None,
confdir=None,
outdir=None,
doctreedir=None,
buildername="html",
confoverrides=None,
status=None,
warning=None,
freshenv=None,
warningiserror=None,
tags=None,
confname="conf.py",
cleanenv=False,
):
2016-05-01 18:12:02 +02:00
application.CONFIG_FILENAME = confname
2021-01-02 06:20:53 +01:00
self.cleanup_trees = [test_root / "generated"]
2016-05-01 18:12:02 +02:00
if srcdir is None:
srcdir = test_root
2021-01-02 06:20:53 +01:00
if srcdir == "(temp)":
2016-05-01 18:12:02 +02:00
tempdir = Path(tempfile.mkdtemp())
self.cleanup_trees.append(tempdir)
2021-01-02 06:20:53 +01:00
temproot = tempdir / "root"
2016-05-01 18:12:02 +02:00
test_root.copytree(temproot)
srcdir = temproot
else:
srcdir = Path(srcdir)
2021-01-02 06:20:53 +01:00
self.builddir = srcdir.joinpath("_build")
2016-05-01 18:12:02 +02:00
if confdir is None:
confdir = srcdir
if outdir is None:
outdir = srcdir.joinpath(self.builddir, buildername)
if not outdir.isdir():
outdir.makedirs()
self.cleanup_trees.insert(0, outdir)
if doctreedir is None:
2021-01-02 06:20:53 +01:00
doctreedir = srcdir.joinpath(srcdir, self.builddir, "doctrees")
2016-05-01 18:12:02 +02:00
if cleanenv:
self.cleanup_trees.insert(0, doctreedir)
if confoverrides is None:
confoverrides = {}
if status is None:
status = io.StringIO()
if warning is None:
2021-01-02 06:20:53 +01:00
warning = ListOutput("stderr")
2016-05-01 18:12:02 +02:00
if freshenv is None:
freshenv = False
if warningiserror is None:
warningiserror = False
2021-01-02 06:20:53 +01:00
application.Sphinx.__init__(
self,
srcdir,
confdir,
outdir,
doctreedir,
buildername,
confoverrides,
status,
warning,
freshenv,
warningiserror,
tags,
)
2016-05-01 18:12:02 +02:00
def cleanup(self, doctrees=False):
for tree in self.cleanup_trees:
shutil.rmtree(tree, True)
def with_app(*args, **kwargs):
"""
Make a TestApp with args and kwargs, pass it to the test and clean up
properly.
"""
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
def generator(func):
@wraps(func)
def deco(*args2, **kwargs2):
app = SphinxTestApplication(*args, **kwargs)
2016-05-01 18:12:02 +02:00
func(app, *args2, **kwargs2)
# don't execute cleanup if test failed
app.cleanup()
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
return deco
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
return generator
def gen_with_app(*args, **kwargs):
"""
Make a TestApp with args and kwargs, pass it to the test and clean up
properly.
"""
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
def generator(func):
@wraps(func)
def deco(*args2, **kwargs2):
app = SphinxTestApplication(*args, **kwargs)
2016-05-01 18:12:02 +02:00
for item in func(app, *args2, **kwargs2):
yield item
# don't execute cleanup if test failed
app.cleanup()
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
return deco
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
return generator
2016-05-01 18:12:02 +02:00
def with_tempdir(func):
def new_func():
tempdir = Path(tempfile.mkdtemp())
func(tempdir)
tempdir.rmtree()
2021-01-02 06:20:53 +01:00
2016-05-01 18:12:02 +02:00
new_func.__name__ = func.__name__
return new_func
2016-05-01 18:12:02 +02:00
def write_file(name, contents):
2021-01-02 06:20:53 +01:00
f = open(str(name), "wb")
2016-05-01 18:12:02 +02:00
f.write(contents)
f.close()
2016-05-01 18:12:02 +02:00
def sprint(*args):
2021-01-02 06:20:53 +01:00
sys.stderr.write(" ".join(map(str, args)) + "\n")