tests: use pathlib

Updating the testing implementation to use the pathlib module for all
path-related operations.

This is part of an ongoing maintenance task to the implementation to use
newer capabilities of Python that are supported on the oldest interpreter
version this extension supports.

Signed-off-by: James Knight <james.d.knight@live.com>

tests/__main__.py

@@ -1,10 +1,10 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from pathlib import Path
 from tests.lib import enable_sphinx_info
 import argparse
 import fnmatch
-import os
 import sys
 import unittest
 
@@ -50,8 +50,8 @@ def main():
         unittest.TestCase.shortDescription = lambda _: None
 
     # discover unit tests
-    test_base = os.path.dirname(os.path.realpath(__file__))
-    unit_tests_dir = os.path.join(test_base, 'unit-tests')
+    test_base = Path(__file__).parent.resolve()
+    unit_tests_dir = test_base / 'unit-tests'
     unit_tests = loader.discover(unit_tests_dir)
 
     # check if a unit test name was provided

tests/lib/__init__.py

@@ -4,6 +4,7 @@
 from contextlib import contextmanager
 from contextlib import suppress
 from copy import deepcopy
+from pathlib import Path
 from sphinx.application import Sphinx
 from sphinx.util.console import color_terminal
 from sphinx.util.console import nocolor
@@ -510,13 +511,14 @@ def prepare_dirs(container=None, postfix=None):
         while frame and not frame.f_code.co_name.startswith('test_'):
             frame = frame.f_back
         container = frame.f_code.co_name if frame else 'unknown'
-    lib_dir = os.path.dirname(os.path.realpath(__file__))
-    test_dir = os.path.join(lib_dir, os.pardir)
-    base_dir = os.path.join(test_dir, os.pardir)
-    output_dir = os.path.join(base_dir, 'output')
-    container_dir = os.path.abspath(os.path.join(output_dir, container))
+
+    lib_dir = Path(__file__).parent.resolve()
+    test_dir = lib_dir.parent
+    base_dir = test_dir.parent
+    output_dir = base_dir / 'output'
+    container_dir = output_dir / container
     if postfix:
-        container_dir += postfix
+        container_dir = container_dir.parent / (container_dir.name + postfix)
 
     shutil.rmtree(container_dir, ignore_errors=True)
 
@@ -551,7 +553,7 @@ def prepare_sphinx(src_dir, config=None, out_dir=None, extra_config=None,
     conf = dict(config) if config else {}
     if extra_config:
         conf.update(extra_config)
-    conf_dir = src_dir if config is None else None
+    conf_dir = str(src_dir) if config is None else None
     warnerr = not relax
 
     sts = None
@@ -570,14 +572,14 @@ def prepare_sphinx(src_dir, config=None, out_dir=None, extra_config=None,
     if not out_dir:
         out_dir = prepare_dirs()
 
-    doctrees_dir = os.path.join(out_dir, '.doctrees')
+    doctrees_dir = out_dir / '.doctrees'
 
     with docutils_namespace():
         app = Sphinx(
-            src_dir,                 # output for document sources
+            str(src_dir),            # output for document sources
             conf_dir,                # configuration directory
-            out_dir,                 # output for generated documents
-            doctrees_dir,            # output for doctree files
+            str(out_dir),            # output for generated documents
+            str(doctrees_dir),       # output for doctree files
             builder,                 # builder to execute
             confoverrides=conf,      # load provided configuration (volatile)
             status=sts,              # status output
@@ -617,7 +619,7 @@ def prepare_sphinx_filenames(src_dir, filenames, configs=None):
     """
     files = []
     for filename in filenames:
-        files.append(os.path.join(src_dir, filename + '.rst'))
+        files.append(str(src_dir / (filename + '.rst')))
 
     if configs:
         root_doc = 'index'

tests/lib/parse.py

@@ -3,7 +3,7 @@
 
 from bs4 import BeautifulSoup
 from contextlib import contextmanager
-import os
+from pathlib import Path
 
 
 @contextmanager
@@ -24,12 +24,12 @@ def parse(filename, dirname=None):
         the parsed output
     """
     if dirname:
-        target = os.path.join(dirname, filename)
+        target = Path(dirname) / filename
     else:
-        target = filename
+        target = Path(filename)
 
-    target += '.conf'
+    target = target.parent / (target.name + '.conf')
 
-    with open(target, encoding='utf-8') as fp:
+    with target.open(encoding='utf-8') as fp:
         soup = BeautifulSoup(fp, 'html.parser')
         yield soup

tests/lib/testcase.py

@@ -2,10 +2,10 @@
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
 from functools import wraps
+from pathlib import Path
 from tests.lib import build_sphinx
 from tests.lib import prepare_conf
 from tests.lib import prepare_sphinx
-import os
 import unittest
 
 # default builder to test against
@@ -42,13 +42,12 @@ def setUpClass(cls):
         cls.config = prepare_conf()
 
         # provide a reference to common directories
-        lib_dir = os.path.dirname(os.path.realpath(__file__))
-        tests_dir = os.path.join(lib_dir, os.pardir)
-        unit_tests_dir = os.path.join(tests_dir, 'unit-tests')
+        lib_dir = Path(__file__).parent.resolve()
+        unit_tests_dir = lib_dir.parent / 'unit-tests'
 
-        cls.assets_dir = os.path.join(unit_tests_dir, 'assets')
-        cls.datasets = os.path.join(unit_tests_dir, 'datasets')
-        cls.templates_dir = os.path.join(unit_tests_dir, 'templates')
+        cls.assets_dir = unit_tests_dir / 'assets'
+        cls.datasets = unit_tests_dir / 'datasets'
+        cls.templates_dir = unit_tests_dir / 'templates'
 
     def build(self, *args, **kwargs):
         """

tests/test_sample.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from pathlib import Path
 from tests.lib import build_sphinx
 from tests.lib import enable_sphinx_info
 from tests.lib import prepare_dirs
@@ -40,26 +41,26 @@ def main():
         print('[sample] (error) missing tox ini environment variable')
         return 1
 
-    sample_base = os.environ['TOX_INI_DIR']
-    sample_set_dir = os.path.dirname(sample_base)
-    sample_name = os.path.basename(sample_base)
+    sample_base = Path(os.environ['TOX_INI_DIR'])
+    sample_set_dir = sample_base.parent
+    sample_name = sample_base.name
     container = 'sample-' + sample_name
     if args.builder:
         container += '-' + args.builder
 
     # check if there is a sub-folder the documentation will be found under
     if 'SAMPLE_DIR' in os.environ:
-        sample_dir = os.path.join(sample_base, os.environ['SAMPLE_DIR'])
+        sample_dir = sample_base / os.environ['SAMPLE_DIR']
     else:
         sample_dir = sample_base
 
     doc_dir = prepare_dirs(container)
 
     # extract any shared confguration values and inject them into the
     # define list
-    shared_config = os.path.join(sample_set_dir, 'config.py')
-    if os.path.isfile(shared_config):
-        with open(shared_config, encoding='utf-8') as f:
+    shared_config = sample_set_dir / 'config.py'
+    if shared_config.is_file():
+        with shared_config.open(encoding='utf-8') as f:
             data = f.read()
 
         ast_data = ast.parse(data, filename=shared_config)

tests/test_sandbox.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from pathlib import Path
 from sphinxcontrib.confluencebuilder.exceptions import ConfluenceBadApiError
 from sphinxcontrib.confluencebuilder.publisher import ConfluencePublisher
 from tests.lib import build_sphinx
@@ -13,9 +14,8 @@
 
 
 def process_sandbox(target_sandbox, builder=None, defines=None):
-    test_dir = os.path.dirname(os.path.realpath(__file__))
-    base_dir = os.path.join(test_dir, os.pardir)
-    sandbox_dir = os.path.join(base_dir, target_sandbox)
+    test_dir = Path(__file__).parent.resolve()
+    sandbox_dir = test_dir.parent / target_sandbox
 
     container = 'sandbox-test'
     if builder:
@@ -27,12 +27,11 @@ def process_sandbox(target_sandbox, builder=None, defines=None):
 
 
 def process_raw_upload(target_sandbox):
-    test_dir = os.path.dirname(os.path.realpath(__file__))
-    base_dir = os.path.join(test_dir, os.pardir)
-    sandbox_dir = os.path.join(base_dir, target_sandbox)
-    raw_file = os.path.join(sandbox_dir, 'raw.conf')
+    test_dir = Path(__file__).parent.resolve()
+    sandbox_dir = test_dir.parent / target_sandbox
+    raw_file = sandbox_dir / 'raw.conf'
 
-    if not os.path.exists(raw_file):
+    if not raw_file.is_file():
         print('[sandbox] missing file', raw_file)
         return
 
@@ -47,7 +46,7 @@ def process_raw_upload(target_sandbox):
                 'labels': [],
             }
 
-            with open(raw_file, 'r', encoding='utf-8') as f:
+            with raw_file.open(encoding='utf-8') as f:
                 data['content'] = f.read()
 
             print('[sandbox] publishing page...')

tests/test_validation.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from pathlib import Path
 from sphinxcontrib.confluencebuilder.state import ConfluenceState
 from tests.lib import build_sphinx
 from tests.lib import enable_sphinx_info
@@ -93,11 +94,11 @@ def setUpClass(cls):
 """.format(cls.test_key, cls.test_desc)
 
         # find validate-sets base folder
-        test_dir = os.path.dirname(os.path.realpath(__file__))
-        cls.datasets = os.path.join(test_dir, 'validation-sets')
+        test_dir = Path(__file__).parent.resolve()
+        cls.datasets = test_dir / 'validation-sets'
 
         # setup base structure
-        dataset = os.path.join(cls.datasets, 'base')
+        dataset = cls.datasets / 'base'
         doc_dir = prepare_dirs('validation-set-base')
 
         config = cls.config.clone()
@@ -178,7 +179,7 @@ def _test_restructuredtext(self, editor):
         config = self._prepare_editor(editor)
         config['confluence_sourcelink']['container'] += 'restructuredtext/'
 
-        dataset = os.path.join(self.datasets, 'restructuredtext')
+        dataset = self.datasets / 'restructuredtext'
         doc_dir = prepare_dirs('validation-set-restructuredtext-' + editor)
 
         # inject a navdoc to the header/footer start page
@@ -206,7 +207,7 @@ def _test_sphinx(self, editor):
         config = self._prepare_editor(editor)
         config['confluence_sourcelink']['container'] += 'sphinx/'
 
-        dataset = os.path.join(self.datasets, 'sphinx')
+        dataset = self.datasets / 'sphinx'
         doc_dir = prepare_dirs('validation-set-sphinx-' + editor)
 
         # inject a navdoc to the header/footer start page
@@ -235,7 +236,7 @@ def _test_markdown(self, editor):
         config['confluence_sourcelink']['container'] += 'markdown/'
         config['extensions'].append('myst_parser')
 
-        dataset = os.path.join(self.datasets, 'markdown')
+        dataset = self.datasets / 'markdown'
         doc_dir = prepare_dirs('validation-set-markdown-' + editor)
 
         # inject a navdoc to the header/footer start page
@@ -277,7 +278,7 @@ def _test_extensions(self, editor):
         else:
             config['graphviz_output_format'] = 'svg'
 
-        dataset = os.path.join(self.datasets, 'extensions')
+        dataset = self.datasets / 'extensions'
         doc_dir = prepare_dirs('validation-set-extensions-' + editor)
 
         # inject a navdoc to the header/footer start page
@@ -296,9 +297,9 @@ def navdocs_transform(builder, docnames):
             return docnames
         config['confluence_navdocs_transform'] = navdocs_transform
 
-        dataset = os.path.join(self.datasets, 'extensions')
+        dataset = self.datasets / 'extensions'
         doc_dir = prepare_dirs('validation-set-extensions')
-        sys.path.insert(0, os.path.join(dataset, 'src'))
+        sys.path.insert(0, str(dataset / 'src'))
 
         build_sphinx(dataset, config=config, out_dir=doc_dir)
 

tests/unit-tests/test_cache.py

@@ -1,10 +1,10 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from pathlib import Path
 from sphinxcontrib.confluencebuilder.util import temp_dir
 from tests.lib import prepare_dirs
 from tests.lib.testcase import ConfluenceTestCase
-import os
 
 
 class TestCache(ConfluenceTestCase):
@@ -15,7 +15,7 @@ def test_cache_outdated_config(self):
         # Confluence-specific configuration flags that a rebuild is needed.
 
         config = dict(self.config)
-        dataset = os.path.join(self.datasets, 'minimal')
+        dataset = self.datasets / 'minimal'
         out_dir = prepare_dirs()
         src_docs = []
 
@@ -90,23 +90,24 @@ def env_get_outdated(app, env, added, changed, removed):
 
             return []
 
-        def write_doc(fname, data):
+        def write_doc(file, data):
             try:
-                with open(fname, 'w') as f:
+                with file.open('w') as f:
                     f.write(data)
             except OSError:
                 pass
 
         with temp_dir() as src_dir:
-            index_file = os.path.join(src_dir, 'index.rst')
+            src_dir = Path(src_dir)
+            index_file = src_dir / 'index.rst'
             write_doc(index_file, '''\
 index
 =====
 
 content
 ''')
 
-            second_file = os.path.join(src_dir, 'second.rst')
+            second_file = src_dir / 'second.rst'
             write_doc(second_file, '''\
 :orphan: