Merge pull request #886 from sphinx-contrib/use-pathlib-part1

Use pathlib (Part 1)

Author: jdknight

sphinxcontrib/confluencebuilder/__init__.py

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
-from os import path
+from pathlib import Path
 from sphinx.util import docutils
 from sphinxcontrib.confluencebuilder.builder import ConfluenceBuilder
 from sphinxcontrib.confluencebuilder.config import handle_config_inited
@@ -58,9 +58,9 @@ def setup(app):
     app.add_builder(SingleConfluenceBuilder)
 
     # register this extension's locale
-    package_dir = path.abspath(path.dirname(__file__))
-    locale_dir = path.join(package_dir, 'locale')
-    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
+    package_dir = Path(__file__).parent.resolve()
+    locale_dir = package_dir / 'locale'
+    app.add_message_catalog(MESSAGE_CATALOG_NAME, str(locale_dir))
 
     # ##########################################################################
 

sphinxcontrib/confluencebuilder/builder.py

@@ -5,12 +5,12 @@
 from collections import defaultdict
 from docutils import nodes
 from docutils.io import StringOutput
+from pathlib import Path
 from os import path
 from sphinx import addnodes
 from sphinx import version_info as sphinx_version_info
 from sphinx.builders import Builder
 from sphinx.locale import _ as SL
-from sphinx.util.osutil import ensuredir
 from sphinxcontrib.confluencebuilder.assets import ConfluenceAssetManager
 from sphinxcontrib.confluencebuilder.assets import ConfluenceSupportedImages
 from sphinxcontrib.confluencebuilder.compat import docutils_findall as findall
@@ -41,7 +41,6 @@
 from sphinxcontrib.confluencebuilder.util import first
 from sphinxcontrib.confluencebuilder.util import handle_cli_file_subset
 from sphinxcontrib.confluencebuilder.writer import ConfluenceWriter
-import os
 import tempfile
 
 
@@ -78,6 +77,7 @@ def __init__(self, app, env=None):
         self.nav_prev = {}
         self.omitted_docnames = []
         self.orphan_docnames = []
+        self.out_dir = Path(self.outdir)
         self.parent_id = None
         self.publish_allowlist = None
         self.publish_denylist = None
@@ -135,7 +135,7 @@ def init(self):
         # files are build -- use this to hint to using a temporary directory
         # on the same partition the output directory to help prevent issues.
         self._imgmath_tempdir = tempfile.mkdtemp(
-            prefix='.imgmath-', dir=self.outdir)
+            prefix='.imgmath-', dir=self.out_dir)
 
         if self.config.confluence_publish:
             process_ask_configs(self.config)
@@ -469,15 +469,15 @@ def write_doc(self, docname, doctree):
         destination = StringOutput(encoding='utf-8')
 
         self.writer.write(doctree, destination)
-        outfilename = path.join(self.outdir, self.file_transform(docname))
+        out_file = self.out_dir / self.file_transform(docname)
         if self.writer.output is not None:
-            ensuredir(path.dirname(outfilename))
+            out_file.parent.mkdir(parents=True, exist_ok=True)
             try:
-                with open(outfilename, 'w', encoding='utf-8') as file:
+                with out_file.open('w', encoding='utf-8') as file:
                     if self.writer.output:
                         file.write(self.writer.output)
             except OSError as err:
-                self.warn(f'error writing file {outfilename}: {err}')
+                self.warn(f'error writing file {out_file}: {err}')
 
         self._cache_info.track_page_hash(docname)
 
@@ -760,10 +760,10 @@ def finish(self):
                 if self._check_publish_skip(docname):
                     self.verbose(docname + ' skipped due to configuration')
                     continue
-                docfile = path.join(self.outdir, self.file_transform(docname))
+                docfile = self.out_dir / self.file_transform(docname)
 
                 try:
-                    with open(docfile, encoding='utf-8') as file:
+                    with docfile.open(encoding='utf-8') as file:
                         output = file.read()
                         self.publish_doc(docname, output)
                 except OSError as err:
@@ -774,10 +774,10 @@ def finish(self):
             self.info('done')
 
             if self.config.confluence_publish_intersphinx:
-                inv = path.join(self.outdir, 'objects.inv')
-                if os.path.exists(inv):
+                inventory_db = self.out_dir / 'objects.inv'
+                if inventory_db.is_file():
                     self.verbose('registering intersphinx database attachment')
-                    self.assets.add(inv, self.config.root_doc)
+                    self.assets.add(str(inventory_db), self.config.root_doc)
                 else:
                     self.verbose('no generated intersphinx database detected')
 
@@ -948,9 +948,9 @@ def _generate_special_document(self, docname, generator):
                         self.config.confluence_footer_data)
 
         # generate/replace the document in the output directory
-        fname = path.join(self.outdir, docname + self.file_suffix)
+        out_file = self.out_dir / (docname + self.file_suffix)
         try:
-            with open(fname, 'w', encoding='utf-8') as f:
+            with out_file.open('w', encoding='utf-8') as f:
                 f.write(self._cached_header_data)
                 generator(self, docname, f)
                 f.write(self._cached_footer_data)

sphinxcontrib/confluencebuilder/env.py

@@ -1,9 +1,9 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from pathlib import Path
 from sphinxcontrib.confluencebuilder.util import ConfluenceUtil
 import json
-import os
 
 
 # base filename for cache information
@@ -21,16 +21,14 @@
 
 class ConfluenceCacheInfo:
     def __init__(self, builder):
-        outdir = builder.outdir
-
         self.builder = builder
         self.env = builder.env
         self._active_dochash = {}
         self._active_hash = None
         self._active_pids = {}
-        self._cache_cfg_file = os.path.join(outdir, ENV_CACHE_CONFIG)
-        self._cache_hash_file = os.path.join(outdir, ENV_CACHE_DOCHASH)
-        self._cache_publish_file = os.path.join(outdir, ENV_CACHE_PUBLISH)
+        self._cache_cfg_file = builder.out_dir / ENV_CACHE_CONFIG
+        self._cache_hash_file = builder.out_dir / ENV_CACHE_DOCHASH
+        self._cache_publish_file = builder.out_dir / ENV_CACHE_PUBLISH
         self._cached_dochash = {}
         self._cached_hash = None
         self._cached_pids = {}
@@ -76,13 +74,13 @@ def is_outdated(self, docname):
 
         # if there is not output file, considered outdated
         dst_filename = self.builder.file_transform(docname)
-        dst_file = os.path.join(self.builder.outdir, dst_filename)
-        if not os.path.exists(dst_file):
+        dst_file = self.builder.out_dir / dst_filename
+        if not dst_file.is_file():
             return True
 
         # if there is not source file (removed document), considered outdated
-        src_file = self.env.doc2path(docname)
-        if not os.path.exists(src_file):
+        src_file = Path(self.env.doc2path(docname))
+        if not src_file.is_file():
             return True
 
         # check if the hashes do not match; if not, this document is outdated
@@ -173,23 +171,23 @@ def load_cache(self):
         """
 
         try:
-            with open(self._cache_cfg_file, encoding='utf-8') as f:
+            with self._cache_cfg_file.open(encoding='utf-8') as f:
                 self._cached_hash = json.load(f).get('hash')
         except FileNotFoundError:
             pass
         except OSError as e:
             self.builder.warn('failed to load cache (config): ' + e)
 
         try:
-            with open(self._cache_hash_file, encoding='utf-8') as f:
+            with self._cache_hash_file.open(encoding='utf-8') as f:
                 self._cached_dochash = json.load(f)
         except FileNotFoundError:
             pass
         except OSError as e:
             self.builder.warn('failed to load cache (hashes): ' + e)
 
         try:
-            with open(self._cache_publish_file, encoding='utf-8') as f:
+            with self._cache_publish_file.open(encoding='utf-8') as f:
                 self._cached_pids = json.load(f)
         except FileNotFoundError:
             pass
@@ -213,19 +211,19 @@ def save_cache(self):
         new_dochashs.update(self._active_dochash)
 
         try:
-            with open(self._cache_cfg_file, 'w', encoding='utf-8') as f:
+            with self._cache_cfg_file.open('w', encoding='utf-8') as f:
                 json.dump(new_cfg, f)
         except OSError as e:
             self.builder.warn('failed to save cache (config): ' + e)
 
         try:
-            with open(self._cache_hash_file, 'w', encoding='utf-8') as f:
+            with self._cache_hash_file.open('w', encoding='utf-8') as f:
                 json.dump(new_dochashs, f)
         except OSError as e:
             self.builder.warn('failed to save cache (hashes): ' + e)
 
         try:
-            with open(self._cache_publish_file, 'w', encoding='utf-8') as f:
+            with self._cache_publish_file.open('w', encoding='utf-8') as f:
                 json.dump(self._active_pids, f)
         except OSError as e:
             self.builder.warn('failed to save cache (pids): ' + e)

sphinxcontrib/confluencebuilder/intersphinx.py

@@ -2,7 +2,6 @@
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 # Copyright 2007-2020 by the Sphinx team (sphinx-doc/sphinx#AUTHORS)
 
-from os import path
 from sphinxcontrib.confluencebuilder.logger import ConfluenceLogger as logger
 import re
 import requests
@@ -32,7 +31,8 @@ def escape(string):
     else:
         pages_part = 'pages/viewpage.action?pageId={}'
 
-    with open(path.join(builder.outdir, INVENTORY_FILENAME), 'wb') as f:
+    inventory_db = builder.out_dir / INVENTORY_FILENAME
+    with inventory_db.open('wb') as f:
         # header
         f.write((
             '# Sphinx inventory version 2\n'

sphinxcontrib/confluencebuilder/svg.py

@@ -3,12 +3,10 @@
 
 from hashlib import sha256
 from sphinx.util.images import guess_mimetype
-from sphinx.util.osutil import ensuredir
 from sphinxcontrib.confluencebuilder.logger import ConfluenceLogger as logger
 from sphinxcontrib.confluencebuilder.util import convert_length
 from sphinxcontrib.confluencebuilder.util import extract_length
 from sphinxcontrib.confluencebuilder.util import find_env_abspath
-import os
 import xml.etree.ElementTree as xml_et
 
 
@@ -194,23 +192,23 @@ def confluence_supported_svg(builder, node):
         return
 
     fname = sha256(svg_data).hexdigest() + '.svg'
-    outfn = os.path.join(builder.outdir, builder.imagedir, 'svgs', fname)
+    out_file = builder.out_dir / builder.imagedir / 'svgs' / fname
 
     # write the new svg file (if needed)
-    if not os.path.isfile(outfn):
+    if not out_file.is_file():
         logger.verbose('generating compatible svg of: %s' % uri)
-        logger.verbose('generating compatible svg to: %s' % outfn)
+        logger.verbose(f'generating compatible svg to: {out_file}')
 
-        ensuredir(os.path.dirname(outfn))
+        out_file.parent.mkdir(parents=True, exist_ok=True)
         try:
-            with open(outfn, 'wb') as f:
+            with out_file.open('wb') as f:
                 f.write(svg_data)
         except (IOError, OSError) as err:
             builder.warn('error writing svg: %s' % err)
             return
 
     # replace the required node attributes
-    node['uri'] = outfn
+    node['uri'] = str(out_file)
 
     if 'height' in node:
         del node['height']

sphinxcontrib/confluencebuilder/transmute/__init__.py

@@ -2,7 +2,6 @@
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
 from docutils import nodes
-from os import path
 from sphinx.util.math import wrap_displaymath
 from sphinxcontrib.confluencebuilder.compat import docutils_findall as findall
 from sphinxcontrib.confluencebuilder.logger import ConfluenceLogger
@@ -136,7 +135,7 @@ def __init__(self, builder):
 
             new_node = nodes.image(
                 candidates={'?'},
-                uri=path.join(builder.outdir, mf),
+                uri=str(builder.out_dir / mf),
                 **node.attributes)
 
             if depth is not None:

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'