From 7d6374d983cc757e8bb7911da13f2dce7d69ec36 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 1 Feb 2020 10:58:28 +0900 Subject: [PATCH 1/2] testing: Add Path.read_text() and Path.read_bytes() To migrate pathlib.Path in future, compatibile methods are needed for our Path class. --- CHANGES | 2 ++ doc/extdev/deprecated.rst | 10 ++++++++++ sphinx/testing/path.py | 19 +++++++++++++++++++ 3 files changed, 31 insertions(+) diff --git a/CHANGES b/CHANGES index a3f88000b..226421776 100644 --- a/CHANGES +++ b/CHANGES @@ -27,6 +27,8 @@ Deprecated ---------- * ``sphinx.domains.std.StandardDomain.add_object()`` +* ``sphinx.testing.path.Path.text()`` +* ``sphinx.testing.path.Path.bytes()`` Features added -------------- diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 50b683d09..a1528b763 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -31,6 +31,16 @@ The following is a list of deprecated interfaces. - 5.0 - ``sphinx.domains.std.StandardDomain.note_object()`` + * - ``sphinx.testing.path.Path.text()`` + - 3.0 + - 5.0 + - ``sphinx.testing.path.Path.read_text()`` + + * - ``sphinx.testing.path.Path.bytes()`` + - 3.0 + - 5.0 + - ``sphinx.testing.path.Path.read_bytes()`` + * - ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()`` - 2.4 - 4.0 diff --git a/sphinx/testing/path.py b/sphinx/testing/path.py index 1c883af2f..4c3702e3d 100644 --- a/sphinx/testing/path.py +++ b/sphinx/testing/path.py @@ -10,8 +10,11 @@ import builtins import os import shutil import sys +import warnings from typing import Any, Callable, IO, List +from sphinx.deprecation import RemovedInSphinx50Warning + FILESYSTEMENCODING = sys.getfilesystemencoding() or sys.getdefaultencoding() @@ -135,6 +138,14 @@ class path(str): f.write(text) def text(self, encoding: str = 'utf-8', **kwargs: Any) -> str: + """ + Returns the text in the file. + """ + warnings.warn('Path.text() is deprecated. Please use read_text() instead.', + RemovedInSphinx50Warning, stacklevel=2) + return self.read_text(encoding, **kwargs) + + def read_text(self, encoding: str = 'utf-8', **kwargs: Any) -> str: """ Returns the text in the file. """ @@ -142,6 +153,14 @@ class path(str): return f.read() def bytes(self) -> builtins.bytes: + """ + Returns the bytes in the file. + """ + warnings.warn('Path.bytes() is deprecated. Please use read_bytes() instead.', + RemovedInSphinx50Warning, stacklevel=2) + return self.read_bytes() + + def read_bytes(self) -> builtins.bytes: """ Returns the bytes in the file. """ From 4dd8b1022f581e8e42db520eb1061f064cbdf63f Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 1 Feb 2020 11:58:51 +0900 Subject: [PATCH 2/2] test: Use read_text() and read_bytes() --- tests/test_build.py | 2 +- tests/test_build_changes.py | 2 +- tests/test_build_epub.py | 34 ++-- tests/test_build_gettext.py | 10 +- tests/test_build_html.py | 38 ++-- tests/test_build_latex.py | 162 +++++++++--------- tests/test_build_linkcheck.py | 4 +- tests/test_build_manpage.py | 6 +- tests/test_build_texinfo.py | 6 +- tests/test_build_text.py | 34 ++-- tests/test_correct_year.py | 2 +- tests/test_directive_code.py | 26 +-- tests/test_domain_cpp.py | 10 +- tests/test_domain_std.py | 4 +- tests/test_ext_apidoc.py | 26 +-- tests/test_ext_autodoc_configs.py | 2 +- tests/test_ext_autosectionlabel.py | 4 +- tests/test_ext_autosummary.py | 16 +- tests/test_ext_coverage.py | 8 +- tests/test_ext_githubpages.py | 2 +- tests/test_ext_graphviz.py | 8 +- tests/test_ext_ifconfig.py | 2 +- tests/test_ext_imgconverter.py | 2 +- tests/test_ext_inheritance_diagram.py | 8 +- tests/test_ext_intersphinx.py | 2 +- tests/test_ext_math.py | 24 +-- tests/test_ext_todo.py | 10 +- tests/test_ext_viewcode.py | 12 +- tests/test_intl.py | 62 +++---- tests/test_quickstart.py | 2 +- tests/test_search.py | 8 +- tests/test_setup_command.py | 2 +- tests/test_smartquotes.py | 18 +- tests/test_templating.py | 4 +- tests/test_theming.py | 14 +- tests/test_toctree.py | 2 +- tests/test_transforms_post_transforms_code.py | 4 +- tests/test_util_fileutil.py | 12 +- 38 files changed, 297 insertions(+), 297 deletions(-) diff --git a/tests/test_build.py b/tests/test_build.py index de73cb6d9..9dcf78165 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -45,7 +45,7 @@ def nonascii_srcdir(request, rootdir, sphinx_test_tempdir): """)) master_doc = srcdir / 'index.txt' - master_doc.write_text(master_doc.text() + dedent(""" + master_doc.write_text(master_doc.read_text() + dedent(""" .. toctree:: %(test_name)s/%(test_name)s diff --git a/tests/test_build_changes.py b/tests/test_build_changes.py index 5adaa5777..2e87fe0bf 100644 --- a/tests/test_build_changes.py +++ b/tests/test_build_changes.py @@ -17,7 +17,7 @@ def test_build(app): app.build() # TODO: Use better checking of html content - htmltext = (app.outdir / 'changes.html').text() + htmltext = (app.outdir / 'changes.html').read_text() assert 'New in version 0.6: Some funny stuff.' in htmltext assert 'Changed in version 0.6: Even more funny stuff.' in htmltext assert 'Deprecated since version 0.6: Boring stuff.' in htmltext diff --git a/tests/test_build_epub.py b/tests/test_build_epub.py index 9436ac020..a5780b04f 100644 --- a/tests/test_build_epub.py +++ b/tests/test_build_epub.py @@ -67,11 +67,11 @@ class EPUBElementTree: @pytest.mark.sphinx('epub', testroot='basic') def test_build_epub(app): app.build() - assert (app.outdir / 'mimetype').text() == 'application/epub+zip' + assert (app.outdir / 'mimetype').read_text() == 'application/epub+zip' assert (app.outdir / 'META-INF' / 'container.xml').exists() # toc.ncx - toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').text()) + toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_text()) assert toc.find("./ncx:docTitle/ncx:text").text == 'Python' # toc.ncx / head @@ -91,7 +91,7 @@ def test_build_epub(app): assert navlabel.text == 'The basic Sphinx documentation for testing' # content.opf - opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').text()) + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text()) # content.opf / metadata metadata = opf.find("./idpf:metadata") @@ -143,7 +143,7 @@ def test_build_epub(app): assert reference.get('href') == 'index.xhtml' # nav.xhtml - nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').text()) + nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').read_text()) assert nav.attrib == {'lang': 'en', '{http://www.w3.org/XML/1998/namespace}lang': 'en'} assert nav.find("./xhtml:head/xhtml:title").text == 'Table of Contents' @@ -163,7 +163,7 @@ def test_epub_cover(app): app.build() # content.opf / metadata - opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').text()) + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text()) cover_image = opf.find("./idpf:manifest/idpf:item[@href='%s']" % app.config.epub_cover[0]) cover = opf.find("./idpf:metadata/idpf:meta[@name='cover']") assert cover @@ -175,7 +175,7 @@ def test_nested_toc(app): app.build() # toc.ncx - toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').bytes()) + toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_bytes()) assert toc.find("./ncx:docTitle/ncx:text").text == 'Python' # toc.ncx / navPoint @@ -205,7 +205,7 @@ def test_nested_toc(app): anchor = elem.find("./xhtml:a") return (anchor.get('href'), anchor.text) - nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').bytes()) + nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').read_bytes()) toc = nav.findall("./xhtml:body/xhtml:nav/xhtml:ol/xhtml:li") assert len(toc) == 4 assert navinfo(toc[0]) == ('index.xhtml', @@ -230,7 +230,7 @@ def test_escaped_toc(app): app.build() # toc.ncx - toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').bytes()) + toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_bytes()) assert toc.find("./ncx:docTitle/ncx:text").text == 'need "escaped" project' # toc.ncx / navPoint @@ -260,7 +260,7 @@ def test_escaped_toc(app): anchor = elem.find("./xhtml:a") return (anchor.get('href'), anchor.text) - nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').bytes()) + nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').read_bytes()) toc = nav.findall("./xhtml:body/xhtml:nav/xhtml:ol/xhtml:li") assert len(toc) == 4 assert navinfo(toc[0]) == ('index.xhtml', @@ -286,7 +286,7 @@ def test_epub_writing_mode(app): app.build() # horizontal / page-progression-direction - opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').text()) + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text()) assert opf.find("./idpf:spine").get('page-progression-direction') == 'ltr' # horizontal / ibooks:scroll-axis @@ -294,7 +294,7 @@ def test_epub_writing_mode(app): assert metadata.find("./idpf:meta[@property='ibooks:scroll-axis']").text == 'vertical' # horizontal / writing-mode (CSS) - css = (app.outdir / '_static' / 'epub.css').text() + css = (app.outdir / '_static' / 'epub.css').read_text() assert 'writing-mode: horizontal-tb;' in css # vertical @@ -303,7 +303,7 @@ def test_epub_writing_mode(app): app.build() # vertical / page-progression-direction - opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').text()) + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text()) assert opf.find("./idpf:spine").get('page-progression-direction') == 'rtl' # vertical / ibooks:scroll-axis @@ -311,7 +311,7 @@ def test_epub_writing_mode(app): assert metadata.find("./idpf:meta[@property='ibooks:scroll-axis']").text == 'horizontal' # vertical / writing-mode (CSS) - css = (app.outdir / '_static' / 'epub.css').text() + css = (app.outdir / '_static' / 'epub.css').read_text() assert 'writing-mode: vertical-rl;' in css @@ -319,7 +319,7 @@ def test_epub_writing_mode(app): def test_epub_anchor_id(app): app.build() - html = (app.outdir / 'index.xhtml').text() + html = (app.outdir / 'index.xhtml').read_text() assert '

blah blah blah

' in html assert '

blah blah blah

' in html assert 'see ' in html @@ -330,7 +330,7 @@ def test_epub_assets(app): app.builder.build_all() # epub_sytlesheets (same as html_css_files) - content = (app.outdir / 'index.xhtml').text() + content = (app.outdir / 'index.xhtml').read_text() assert ('' in content) assert ('' in content # files in html_css_files are not outputed @@ -360,7 +360,7 @@ def test_html_download_role(app, status, warning): app.build() assert not (app.outdir / '_downloads' / 'dummy.dat').exists() - content = (app.outdir / 'index.xhtml').text() + content = (app.outdir / 'index.xhtml').read_text() assert ('

  • ' 'dummy.dat

    • ' in content) assert ('

  • ' diff --git a/tests/test_build_gettext.py b/tests/test_build_gettext.py index a6107167a..1c86b8daa 100644 --- a/tests/test_build_gettext.py +++ b/tests/test_build_gettext.py @@ -31,7 +31,7 @@ def test_build_gettext(app): assert (app.outdir / 'subdir.pot').isfile() # regression test for issue #960 - catalog = (app.outdir / 'markup.pot').text() + catalog = (app.outdir / 'markup.pot').read_text() assert 'msgid "something, something else, something more"' in catalog @@ -84,7 +84,7 @@ def test_gettext_index_entries(app): return m.groups()[0] return None - pot = (app.outdir / 'index_entries.pot').text() + pot = (app.outdir / 'index_entries.pot').read_text() msgids = [_f for _f in map(msgid_getter, pot.splitlines()) if _f] expected_msgids = [ @@ -133,7 +133,7 @@ def test_gettext_disable_index_entries(app): return m.groups()[0] return None - pot = (app.outdir / 'index_entries.pot').text() + pot = (app.outdir / 'index_entries.pot').read_text() msgids = [_f for _f in map(msgid_getter, pot.splitlines()) if _f] expected_msgids = [ @@ -156,7 +156,7 @@ def test_gettext_template(app): app.builder.build_all() assert (app.outdir / 'sphinx.pot').isfile() - result = (app.outdir / 'sphinx.pot').text() + result = (app.outdir / 'sphinx.pot').read_text() assert "Welcome" in result assert "Sphinx %(version)s" in result @@ -166,7 +166,7 @@ def test_gettext_template_msgid_order_in_sphinxpot(app): app.builder.build_all() assert (app.outdir / 'sphinx.pot').isfile() - result = (app.outdir / 'sphinx.pot').text() + result = (app.outdir / 'sphinx.pot').read_text() assert re.search( ('msgid "Template 1".*' 'msgid "This is Template 1\\.".*' diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 1d37488fe..a9914d9a0 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -426,7 +426,7 @@ def test_html_download(app): app.build() # subdir/includes.html - result = (app.outdir / 'subdir' / 'includes.html').text() + result = (app.outdir / 'subdir' / 'includes.html').read_text() pattern = ('') matched = re.search(pattern, result) @@ -435,7 +435,7 @@ def test_html_download(app): filename = matched.group(1) # includes.html - result = (app.outdir / 'includes.html').text() + result = (app.outdir / 'includes.html').read_text() pattern = ('') matched = re.search(pattern, result) @@ -454,7 +454,7 @@ def test_html_download_role(app, status, warning): digest_another = md5(b'another/dummy.dat').hexdigest() assert (app.outdir / '_downloads' / digest_another / 'dummy.dat').exists() - content = (app.outdir / 'index.html').text() + content = (app.outdir / 'index.html').read_text() assert (('

  • ' '' @@ -646,7 +646,7 @@ def test_numfig_disabled(app, cached_etree_parse, fname, expect): def test_numfig_without_numbered_toctree_warn(app, warning): app.build() # remove :numbered: option - index = (app.srcdir / 'index.rst').text() + index = (app.srcdir / 'index.rst').read_text() index = re.sub(':numbered:.*', '', index) (app.srcdir / 'index.rst').write_text(index) app.builder.build_all() @@ -746,7 +746,7 @@ def test_numfig_without_numbered_toctree_warn(app, warning): confoverrides={'numfig': True}) def test_numfig_without_numbered_toctree(app, cached_etree_parse, fname, expect): # remove :numbered: option - index = (app.srcdir / 'index.rst').text() + index = (app.srcdir / 'index.rst').read_text() index = re.sub(':numbered:.*', '', index) (app.srcdir / 'index.rst').write_text(index) @@ -1189,7 +1189,7 @@ def test_html_assets(app): assert not (app.outdir / '_static' / '.htaccess').exists() assert not (app.outdir / '_static' / '.htpasswd').exists() assert (app.outdir / '_static' / 'API.html').exists() - assert (app.outdir / '_static' / 'API.html').text() == 'Sphinx-1.4.4' + assert (app.outdir / '_static' / 'API.html').read_text() == 'Sphinx-1.4.4' assert (app.outdir / '_static' / 'css' / 'style.css').exists() assert (app.outdir / '_static' / 'js' / 'custom.js').exists() assert (app.outdir / '_static' / 'rimg.png').exists() @@ -1210,7 +1210,7 @@ def test_html_assets(app): assert not (app.outdir / 'subdir' / '.htpasswd').exists() # html_css_files - content = (app.outdir / 'index.html').text() + content = (app.outdir / 'index.html').read_text() assert '' in content assert ('' in content) @@ -1249,7 +1249,7 @@ def test_html_sourcelink_suffix_empty(app): def test_html_entity(app): app.builder.build_all() valid_entities = {'amp', 'lt', 'gt', 'quot', 'apos'} - content = (app.outdir / 'index.html').text() + content = (app.outdir / 'index.html').read_text() for entity in re.findall(r'&([a-z]+);', content, re.M): assert entity not in valid_entities @@ -1284,7 +1284,7 @@ def test_html_inventory(app): @pytest.mark.sphinx('html', testroot='images', confoverrides={'html_sourcelink_suffix': ''}) def test_html_anchor_for_figure(app): app.builder.build_all() - content = (app.outdir / 'index.html').text() + content = (app.outdir / 'index.html').read_text() assert ('

    The caption of pic' '

    ' in content) @@ -1293,7 +1293,7 @@ def test_html_anchor_for_figure(app): @pytest.mark.sphinx('html', testroot='directives-raw') def test_html_raw_directive(app, status, warning): app.builder.build_all() - result = (app.outdir / 'index.html').text(encoding='utf8') + result = (app.outdir / 'index.html').read_text(encoding='utf8') # standard case assert 'standalone raw directive (HTML)' in result @@ -1337,7 +1337,7 @@ def test_alternate_stylesheets(app, cached_etree_parse, fname, expect): @pytest.mark.sphinx('html', testroot='html_style') def test_html_style(app, status, warning): app.build() - result = (app.outdir / 'index.html').text() + result = (app.outdir / 'index.html').read_text() assert '' in result assert ('' not in result) @@ -1347,7 +1347,7 @@ def test_html_style(app, status, warning): def test_html_remote_images(app, status, warning): app.builder.build_all() - result = (app.outdir / 'index.html').text(encoding='utf8') + result = (app.outdir / 'index.html').read_text(encoding='utf8') assert ('https://www.python.org/static/img/python-logo.png' in result) assert not (app.outdir / 'python-logo.png').exists() @@ -1359,7 +1359,7 @@ def test_html_sidebar(app, status, warning): # default for alabaster app.builder.build_all() - result = (app.outdir / 'index.html').text(encoding='utf8') + result = (app.outdir / 'index.html').read_text(encoding='utf8') assert ('