From 2652fe4b656a65ebd1622bfea29c8db9d98fc88b Mon Sep 17 00:00:00 2001
From: James Knight <james.d.knight@live.com>
Date: Wed, 24 Jul 2024 23:51:47 -0400
Subject: [PATCH 1/5] adjust various module-check flags

Updating checks for certain modules to have a dedicated boolean flag
over mixing a module/None type. This is a bit more explicit and also
helps avoid some static type checks.

Signed-off-by: James Knight <james.d.knight@live.com>
---
 sphinxcontrib/confluencebuilder/__init__.py   | 13 +++++-----
 .../confluencebuilder/transmute/__init__.py   | 22 +++++++++--------
 .../transmute/ext_sphinx_diagrams.py          |  6 ++---
 .../transmute/ext_sphinx_gallery.py           |  6 ++---
 .../transmute/ext_sphinx_toolbox.py           | 24 +++++++++----------
 .../transmute/ext_sphinxcontrib_mermaid.py    |  6 ++---
 6 files changed, 40 insertions(+), 37 deletions(-)

diff --git a/sphinxcontrib/confluencebuilder/__init__.py b/sphinxcontrib/confluencebuilder/__init__.py
index 14a11c7c..c89091f0 100644
--- a/sphinxcontrib/confluencebuilder/__init__.py
+++ b/sphinxcontrib/confluencebuilder/__init__.py
@@ -37,14 +37,16 @@
 # load autosummary extension if available to add additional nodes
 try:
     from sphinx.ext import autosummary
+    has_autosummary = True
 except ImportError:
-    autosummary = None
+    has_autosummary = False
 
 # load imgmath extension if available to handle math configuration options
 try:
     from sphinx.ext import imgmath
+    has_imgmath = True
 except ImportError:
-    imgmath = None
+    has_imgmath = False
 
 __version__ = '2.7.0.dev0'
 
@@ -383,7 +385,7 @@ def confluence_autosummary_support(app):
         app: the sphinx application
     """
 
-    if autosummary:
+    if has_autosummary:
         for ext in app.extensions.values():
             if ext.name == 'sphinx.ext.autosummary':
                 app.registry.add_translation_handlers(
@@ -423,9 +425,8 @@ def confluence_imgmath_support(app):
         app: the sphinx application
     """
 
-    if imgmath is not None:
-        if 'sphinx.ext.imgmath' not in app.config.extensions:
-            imgmath.setup(app)
+    if has_imgmath and 'sphinx.ext.imgmath' not in app.config.extensions:
+        imgmath.setup(app)
 
 
 def confluence_remove_mathnodemigrator(app):
diff --git a/sphinxcontrib/confluencebuilder/transmute/__init__.py b/sphinxcontrib/confluencebuilder/transmute/__init__.py
index ac1a3e4c..d9a0916d 100644
--- a/sphinxcontrib/confluencebuilder/transmute/__init__.py
+++ b/sphinxcontrib/confluencebuilder/transmute/__init__.py
@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
-from contextlib import suppress
 from docutils import nodes
 from sphinx.util.math import wrap_displaymath
 from sphinxcontrib.confluencebuilder.compat import docutils_findall as findall
@@ -23,20 +22,23 @@
     from sphinx.ext.graphviz import GraphvizError
     from sphinx.ext.graphviz import graphviz
     from sphinx.ext.graphviz import render_dot
+    has_graphviz = True
 except ImportError:
-    graphviz = None
+    has_graphviz = False
 
 # load imgmath extension if available to handle math node pre-processing
 try:
     from sphinx.ext import imgmath
+    has_imgmath = True
 except ImportError:
-    imgmath = None
+    has_imgmath = False
 
 # load inheritance_diagram extension if available to handle node pre-processing
-inheritance_diagram = None
-if graphviz:
-    with suppress(ImportError):
-        from sphinx.ext import inheritance_diagram
+try:
+    from sphinx.ext import inheritance_diagram
+    has_inheritance_diagram = True
+except ImportError:
+    has_inheritance_diagram = False
 
 
 def doctree_transmute(builder, doctree):
@@ -112,7 +114,7 @@ def prepare_math_images(builder, doctree):
     if builder.config.confluence_latex_macro:
         return
 
-    if imgmath is None:
+    if not has_imgmath:
         return
 
     # convert Confluence LaTeX blocks into image blocks
@@ -203,7 +205,7 @@ def replace_graphviz_nodes(builder, doctree):
     if 'ext-graphviz' in restricted:
         return
 
-    if graphviz is None:
+    if not has_graphviz:
         return
 
     # graphviz's render_dot call expects a translator to be passed in; mock a
@@ -258,7 +260,7 @@ def replace_inheritance_diagram(builder, doctree):
     if 'ext-inheritance_diagram' in restricted:
         return
 
-    if inheritance_diagram is None:
+    if not has_graphviz or not has_inheritance_diagram:
         return
 
     # graphviz's render_dot call expects a translator to be passed in; mock
diff --git a/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_diagrams.py b/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_diagrams.py
index 3ae84d91..081f079d 100644
--- a/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_diagrams.py
+++ b/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_diagrams.py
@@ -14,9 +14,9 @@
     from sphinx_diagrams import DiagramsError
     from sphinx_diagrams import diagrams as sphinx_diagrams_diagrams
     from sphinx_diagrams import render_diagrams as sphinx_diagrams_render
-    sphinx_diagrams = True
+    has_sphinx_diagrams = True
 except:  # noqa: E722
-    sphinx_diagrams = False
+    has_sphinx_diagrams = False
 
 # re-enable pylint warnings from above
 # pylint: enable=E
@@ -40,7 +40,7 @@ def replace_sphinx_diagrams_nodes(builder, doctree):
     if 'ext-sphinx_diagrams' in restricted:
         return
 
-    if not sphinx_diagrams:
+    if not has_sphinx_diagrams:
         return
 
     # sphinx-diagrams's render call expects a translator to be passed in;
diff --git a/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_gallery.py b/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_gallery.py
index 6c6b1bd9..127decb0 100644
--- a/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_gallery.py
+++ b/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_gallery.py
@@ -11,9 +11,9 @@
 # load sphinx-gallery extension if available
 try:
     from sphinx_gallery.directives import imgsgnode as sphinx_gallery_imgsgnode
-    sphinx_gallery = True
+    has_sphinx_gallery = True
 except:  # noqa: E722
-    sphinx_gallery = False
+    has_sphinx_gallery = False
 
 # re-enable pylint warnings from above
 # pylint: enable=E
@@ -37,7 +37,7 @@ def replace_sphinx_gallery_nodes(builder, doctree):
     if 'ext-sphinx_gallery' in restricted:
         return
 
-    if not sphinx_gallery:
+    if not has_sphinx_gallery:
         return
 
     for node in findall(doctree, sphinx_gallery_imgsgnode):
diff --git a/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_toolbox.py b/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_toolbox.py
index dd27ef94..9683163a 100644
--- a/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_toolbox.py
+++ b/sphinxcontrib/confluencebuilder/transmute/ext_sphinx_toolbox.py
@@ -17,28 +17,28 @@
 # load sphinx_toolbox extension if available to handle node pre-processing
 try:
     from sphinx_toolbox.assets import AssetNode as sphinx_toolbox_AssetNode
-    sphinx_toolbox_assets = True
+    has_sphinx_toolbox_assets = True
 except:  # noqa: E722
-    sphinx_toolbox_assets = False
+    has_sphinx_toolbox_assets = False
 
 try:
     from sphinx_toolbox.collapse import CollapseNode as sphinx_toolbox_CollapseNode
-    sphinx_toolbox_collapse = True
+    has_sphinx_toolbox_collapse = True
 except:  # noqa: E722
-    sphinx_toolbox_collapse = False
+    has_sphinx_toolbox_collapse = False
 
 try:
     from sphinx_toolbox.github.issues import IssueNode as sphinx_toolbox_IssueNode
     from sphinx_toolbox.github.issues import IssueNodeWithName as sphinx_toolbox_IssueNodeWithName
-    sphinx_toolbox_github_issues = True
+    has_sphinx_toolbox_github_issues = True
 except:  # noqa: E722
-    sphinx_toolbox_github_issues = False
+    has_sphinx_toolbox_github_issues = False
 
 try:
     from sphinx_toolbox.github.repos_and_users import GitHubObjectLinkNode as sphinx_toolbox_GitHubObjectLinkNode
-    sphinx_toolbox_github_repos_and_users = True
+    has_sphinx_toolbox_github_repos_and_users = True
 except:  # noqa: E722
-    sphinx_toolbox_github_repos_and_users = False
+    has_sphinx_toolbox_github_repos_and_users = False
 
 # re-enable pylint warnings from above
 # pylint: enable=E
@@ -62,7 +62,7 @@ def replace_sphinx_toolbox_nodes(builder, doctree):
     if 'ext-sphinx_toolbox' in restricted:
         return
 
-    if sphinx_toolbox_assets:
+    if has_sphinx_toolbox_assets:
         for node in findall(doctree, sphinx_toolbox_AssetNode):
             # mock a docname based off the configured sphinx_toolbox's asset
             # directory; which the processing of a download_reference will
@@ -78,14 +78,14 @@ def replace_sphinx_toolbox_nodes(builder, doctree):
             )
             node.replace_self(new_node)
 
-    if sphinx_toolbox_collapse:
+    if has_sphinx_toolbox_collapse:
         for node in findall(doctree, sphinx_toolbox_CollapseNode):
             new_node = confluence_expand(node.rawsource,
                 *node.children, **node.attributes)
             new_node.attributes['title'] = node.label
             node.replace_self(new_node)
 
-    if sphinx_toolbox_github_issues:
+    if has_sphinx_toolbox_github_issues:
         # note: using while loop since replacing issue nodes has observed to
         #  cause an exception while docutils is processing a doctree
         while True:
@@ -103,7 +103,7 @@ def replace_sphinx_toolbox_nodes(builder, doctree):
             new_node = nodes.reference(title, title, refuri=node.issue_url)
             node.replace_self(new_node)
 
-    if sphinx_toolbox_github_repos_and_users:
+    if has_sphinx_toolbox_github_repos_and_users:
         for node in findall(doctree, sphinx_toolbox_GitHubObjectLinkNode):
             new_node = nodes.reference(node.name, node.name, refuri=node.url)
             node.replace_self(new_node)
diff --git a/sphinxcontrib/confluencebuilder/transmute/ext_sphinxcontrib_mermaid.py b/sphinxcontrib/confluencebuilder/transmute/ext_sphinxcontrib_mermaid.py
index 08748156..8ea900b1 100644
--- a/sphinxcontrib/confluencebuilder/transmute/ext_sphinxcontrib_mermaid.py
+++ b/sphinxcontrib/confluencebuilder/transmute/ext_sphinxcontrib_mermaid.py
@@ -14,9 +14,9 @@
     from sphinxcontrib.mermaid import MermaidError
     from sphinxcontrib.mermaid import mermaid
     from sphinxcontrib.mermaid import render_mm as mermaid_render
-    sphinxcontrib_mermaid = True
+    has_sphinxcontrib_mermaid = True
 except:  # noqa: E722
-    sphinxcontrib_mermaid = False
+    has_sphinxcontrib_mermaid = False
 
 # re-enable pylint warnings from above
 # pylint: enable=E
@@ -40,7 +40,7 @@ def replace_sphinxcontrib_mermaid_nodes(builder, doctree):
     if 'ext-sphinxcontrib.mermaid' in restricted:
         return
 
-    if not sphinxcontrib_mermaid:
+    if not has_sphinxcontrib_mermaid:
         return
 
     # mermaid's mermaid_render call expects a translator to be passed in; mock a

From 7e3f751f359281220d641f976534489111eaf72b Mon Sep 17 00:00:00 2001
From: James Knight <james.d.knight@live.com>
Date: Wed, 24 Jul 2024 23:53:12 -0400
Subject: [PATCH 2/5] drop supported image types class

There is no major advantage of defining a `ConfluenceSupportedImages`
helper class versus just attaching the supported images list to the
builder. This change helps use a type that matches the expected type
defined by Sphinx.

Signed-off-by: James Knight <james.d.knight@live.com>
---
 sphinxcontrib/confluencebuilder/assets.py  | 43 ----------------------
 sphinxcontrib/confluencebuilder/builder.py |  7 ++--
 2 files changed, 4 insertions(+), 46 deletions(-)

diff --git a/sphinxcontrib/confluencebuilder/assets.py b/sphinxcontrib/confluencebuilder/assets.py
index 9b884d0a..e7c677ad 100644
--- a/sphinxcontrib/confluencebuilder/assets.py
+++ b/sphinxcontrib/confluencebuilder/assets.py
@@ -9,7 +9,6 @@
 from sphinxcontrib.confluencebuilder.compat import docutils_findall as findall
 from sphinxcontrib.confluencebuilder.logger import ConfluenceLogger as logger
 from sphinxcontrib.confluencebuilder.std.confluence import INVALID_CHARS
-from sphinxcontrib.confluencebuilder.std.confluence import SUPPORTED_IMAGE_TYPES
 from sphinxcontrib.confluencebuilder.util import ConfluenceUtil
 from sphinxcontrib.confluencebuilder.util import find_env_abspath
 
@@ -347,45 +346,3 @@ def _interpret_asset_path(self, node):
             logger.verbose(f'failed to find path: {path}')
 
         return abs_path
-
-
-class ConfluenceSupportedImages:
-    def __init__(self):
-        """
-        confluence support images
-
-        Defines an iterable instance of mime types of supported images types on
-        a Confluence instance. While a typical list can suffice to bind to a
-        builder's `supported_image_types` definition, this instance provides the
-        ability to register additional mime types (via configuration) if
-        supported by a Confluence instance. This provides flexibility for newer
-        Confluence versions as well as custom instances which support their own
-        custom image types.
-        """
-        self._mime_types = list(SUPPORTED_IMAGE_TYPES)
-
-    def __getitem__(self, key):
-        """
-        iterable evaulation of self[key]
-
-        Args:
-            key: the key to evaluate
-
-        Returns:
-            the value for this key
-        """
-        return self._mime_types[key]
-
-    def register(self, type_):
-        """
-        register a mime type to support
-
-        Register an additional mime type to support over the internal list of
-        supported types. This call has no effect if the type is already
-        registered.
-
-        Args:
-            type_: the mime type to add
-        """
-        if type_ not in self._mime_types:
-            self._mime_types.append(type_)
diff --git a/sphinxcontrib/confluencebuilder/builder.py b/sphinxcontrib/confluencebuilder/builder.py
index a93b500b..981f16da 100644
--- a/sphinxcontrib/confluencebuilder/builder.py
+++ b/sphinxcontrib/confluencebuilder/builder.py
@@ -11,7 +11,6 @@
 from sphinx.locale import _ as SL
 from sphinx.util.display import status_iterator
 from sphinxcontrib.confluencebuilder.assets import ConfluenceAssetManager
-from sphinxcontrib.confluencebuilder.assets import ConfluenceSupportedImages
 from sphinxcontrib.confluencebuilder.compat import docutils_findall as findall
 from sphinxcontrib.confluencebuilder.config import process_ask_configs
 from sphinxcontrib.confluencebuilder.config.checks import validate_configuration
@@ -30,6 +29,7 @@
 from sphinxcontrib.confluencebuilder.publisher import ConfluencePublisher
 from sphinxcontrib.confluencebuilder.state import ConfluenceState
 from sphinxcontrib.confluencebuilder.std.confluence import CONFLUENCE_MAX_WIDTH
+from sphinxcontrib.confluencebuilder.std.confluence import SUPPORTED_IMAGE_TYPES
 from sphinxcontrib.confluencebuilder.storage.index import generate_storage_format_domainindex
 from sphinxcontrib.confluencebuilder.storage.index import generate_storage_format_genindex
 from sphinxcontrib.confluencebuilder.storage.search import generate_storage_format_search
@@ -52,7 +52,7 @@ class ConfluenceBuilder(Builder):
     default_translator_class = ConfluenceStorageFormatTranslator
     name = 'confluence'
     format = 'confluence_storage'
-    supported_image_types = ConfluenceSupportedImages()
+    supported_image_types = SUPPORTED_IMAGE_TYPES
     supported_linkcode = True
     supported_remote_images = True
 
@@ -114,7 +114,8 @@ def init(self):
 
         if self.config.confluence_additional_mime_types:
             for type_ in self.config.confluence_additional_mime_types:
-                self.supported_image_types.register(type_)
+                if type_ not in self.supported_image_types:
+                    self.supported_image_types.append(type_)
 
         if 'graphviz_output_format' in self.config:  # noqa: SIM401
             self.graphviz_output_format = self.config['graphviz_output_format']

From 65481a33a990043cd1e9975a006920bbf4fbf5f3 Mon Sep 17 00:00:00 2001
From: James Knight <james.d.knight@live.com>
Date: Thu, 25 Jul 2024 00:04:10 -0400
Subject: [PATCH 3/5] add type hints

Adding a series of type hints into the extension's implementation. This
is an initial set of updates which corrects reports from a mypy run.

Signed-off-by: James Knight <james.d.knight@live.com>
---
 mypy.ini                                      | 25 +++++++++++++
 sphinxcontrib/confluencebuilder/state.py      | 37 ++++++++++---------
 .../confluencebuilder/storage/translator.py   |  3 +-
 sphinxcontrib/confluencebuilder/util.py       | 13 ++++---
 sphinxcontrib/confluencebuilder/writer.py     |  4 +-
 5 files changed, 56 insertions(+), 26 deletions(-)
 create mode 100644 mypy.ini

diff --git a/mypy.ini b/mypy.ini
new file mode 100644
index 00000000..2b8872d2
--- /dev/null
+++ b/mypy.ini
@@ -0,0 +1,25 @@
+[mypy]
+
+# ignore optional jupyter_sphinx module
+[mypy-jupyter_sphinx.*]
+ignore_missing_imports = True
+
+# ignore optional nbsphinx module
+[mypy-nbsphinx.*]
+ignore_missing_imports = True
+
+# ignore optional sphinx_diagrams module
+[mypy-sphinx_diagrams.*]
+ignore_missing_imports = True
+
+# ignore optional sphinx_gallery module
+[mypy-sphinx_gallery.*]
+ignore_missing_imports = True
+
+# ignore optional sphinx_toolbox module
+[mypy-sphinx_toolbox.*]
+ignore_missing_imports = True
+
+# ignore optional sphinxcontrib.mermaid module
+[mypy-sphinxcontrib.mermaid.*]
+ignore_missing_imports = True
diff --git a/sphinxcontrib/confluencebuilder/state.py b/sphinxcontrib/confluencebuilder/state.py
index 97ec7b81..144b4be7 100644
--- a/sphinxcontrib/confluencebuilder/state.py
+++ b/sphinxcontrib/confluencebuilder/state.py
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from __future__ import annotations
 import hashlib
 from sphinxcontrib.confluencebuilder.config.exceptions import ConfluenceConfigError
 from sphinxcontrib.confluencebuilder.logger import ConfluenceLogger as logger
@@ -15,15 +16,15 @@ class ConfluenceState:
     operation. This includes, but not limited to, remember title names for
     documents, tracking reference identifiers to other document names and more.
     """
-    doc2uploadId = {}
-    doc2parentDoc = {}
-    doc2title = {}
-    doc2ttd = {}
-    refid2target = {}
-    title2doc = {}
+    doc2uploadId: dict[str, int] = {}
+    doc2parentDoc: dict[str, str] = {}
+    doc2title: dict[str, str] = {}
+    doc2ttd: dict[str, int] = {}
+    refid2target: dict[str, str] = {}
+    title2doc: dict[str, str] = {}
 
     @staticmethod
-    def register_parent_docname(docname, parent_docname):
+    def register_parent_docname(docname: str, parent_docname: str):
         """
         register a parent docname for a provided docname
 
@@ -41,7 +42,7 @@ def register_parent_docname(docname, parent_docname):
         logger.verbose(f'setting parent of {docname} to: {parent_docname}')
 
     @staticmethod
-    def register_target(refid, target, overwrite=False):
+    def register_target(refid: str, target: str, *, overwrite: bool=False):
         """
         register a reference to a specific (anchor) target
 
@@ -62,7 +63,7 @@ def register_target(refid, target, overwrite=False):
             logger.verbose(f'mapping {refid} to target: {target}{postfix}')
 
     @staticmethod
-    def register_title(docname, title, config):
+    def register_title(docname: str, title: str, config) -> str:
         """
         register the title for the provided document name
 
@@ -127,7 +128,7 @@ def register_title(docname, title, config):
         return title
 
     @staticmethod
-    def register_toctree_depth(docname, depth):
+    def register_toctree_depth(docname: str, depth: int):
         """
         register the toctree-depth for the provided document name
 
@@ -142,7 +143,7 @@ def register_toctree_depth(docname, depth):
         logger.verbose(f'track {docname} toc-depth: {depth}')
 
     @staticmethod
-    def register_upload_id(docname, id_):
+    def register_upload_id(docname: str, id_: int):
         """
         register a page (upload) identifier for a docname
 
@@ -175,7 +176,7 @@ def reset():
         ConfluenceState.title2doc.clear()
 
     @staticmethod
-    def parent_docname(docname):
+    def parent_docname(docname: str) -> str | None:
         """
         return the parent docname (if any) for a provided docname
 
@@ -184,7 +185,7 @@ def parent_docname(docname):
         return ConfluenceState.doc2parentDoc.get(docname)
 
     @staticmethod
-    def target(refid):
+    def target(refid: str) -> str | None:
         """
         return the (anchor) target for a provided reference
 
@@ -193,7 +194,7 @@ def target(refid):
         return ConfluenceState.refid2target.get(refid)
 
     @staticmethod
-    def title(docname, default=None):
+    def title(docname: str, default: str | None = None) -> str | None:
         """
         return the title value for a provided docname
 
@@ -202,7 +203,7 @@ def title(docname, default=None):
         return ConfluenceState.doc2title.get(docname, default)
 
     @staticmethod
-    def toctree_depth(docname):
+    def toctree_depth(docname: str) -> int | None:
         """
         return the toctree-depth value for a provided docname
 
@@ -211,7 +212,7 @@ def toctree_depth(docname):
         return ConfluenceState.doc2ttd.get(docname)
 
     @staticmethod
-    def upload_id(docname):
+    def upload_id(docname: str) -> int | None:
         """
         return the confluence (upload) page id for the provided docname
 
@@ -220,7 +221,7 @@ def upload_id(docname):
         return ConfluenceState.doc2uploadId.get(docname)
 
     @staticmethod
-    def _format_postfix(postfix, docname, config):
+    def _format_postfix(postfix: str, docname: str, config) -> str:
         """
         Format a postfix that may have placeholders.
         All placeholders used must be supported otherwise an error is raised
@@ -239,7 +240,7 @@ def _format_postfix(postfix, docname, config):
         return postfix
 
     @staticmethod
-    def _create_docname_unique_hash(docname, config):
+    def _create_docname_unique_hash(docname: str, config) -> str:
         """
         Create a unique(ish) hash for the given source file to avoid collisions
         when pushing pages to confluence.
diff --git a/sphinxcontrib/confluencebuilder/storage/translator.py b/sphinxcontrib/confluencebuilder/storage/translator.py
index 28ab7b14..534941f3 100644
--- a/sphinxcontrib/confluencebuilder/storage/translator.py
+++ b/sphinxcontrib/confluencebuilder/storage/translator.py
@@ -2,6 +2,7 @@
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 # Copyright 2018-2020 by the Sphinx team (sphinx-doc/sphinx#AUTHORS)
 
+from __future__ import annotations
 from contextlib import suppress
 from docutils import nodes
 from functools import wraps
@@ -85,7 +86,7 @@ def _wrapper(self, *args, **kwargs):
 
 class ConfluenceStorageFormatTranslator(ConfluenceBaseTranslator):
     __tracked_deprecated = False
-    _tracked_unknown_code_lang = []
+    _tracked_unknown_code_lang: list[str] = []
 
     """
     confluence storage format extension translator
diff --git a/sphinxcontrib/confluencebuilder/util.py b/sphinxcontrib/confluencebuilder/util.py
index 4c3c7dcc..a6a7df62 100644
--- a/sphinxcontrib/confluencebuilder/util.py
+++ b/sphinxcontrib/confluencebuilder/util.py
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from __future__ import annotations
 from contextlib import contextmanager
 from pathlib import Path
 from sphinxcontrib.confluencebuilder.std.confluence import API_REST_V1
@@ -228,7 +229,7 @@ def extract_strings_from_file(filename):
     return filelist
 
 
-def find_env_abspath(env, out_dir, path: str):
+def find_env_abspath(env, out_dir, path: str) -> Path | None:
     """
     find an existing absolute path for a provided path in a sphinx environment
 
@@ -278,11 +279,11 @@ def find_env_abspath(env, out_dir, path: str):
         if not abs_path.is_file():
             abs_path = out_dir / normalized_path
 
-    # if no asset can be found, ensure a `None` path is returned
-    if not abs_path.is_file():
-        abs_path = None
+    if abs_path.is_file():
+        return abs_path
 
-    return abs_path
+    # if no asset can be found, ensure a `None` path is returned
+    return None
 
 
 def first(it):
@@ -397,7 +398,7 @@ def remove_nonspace_control_chars(text):
         or unicodedata.category(c) != 'Cc')
 
 
-def str2bool(value):
+def str2bool(value) -> bool:
     """
     returns the boolean value for a string
 
diff --git a/sphinxcontrib/confluencebuilder/writer.py b/sphinxcontrib/confluencebuilder/writer.py
index f037b66e..441c346f 100644
--- a/sphinxcontrib/confluencebuilder/writer.py
+++ b/sphinxcontrib/confluencebuilder/writer.py
@@ -1,13 +1,15 @@
 # SPDX-License-Identifier: BSD-2-Clause
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
+from __future__ import annotations
 from docutils import writers
+from typing import Any
 
 
 class ConfluenceWriter(writers.Writer):
     supported = ('text',)
     settings_spec = ('No options here.', '', ())
-    settings_defaults = {}
+    settings_defaults: dict[str, Any] = {}
 
     def __init__(self, builder):
         writers.Writer.__init__(self)

From 86555529431b03e41f0a512725b62d645299972a Mon Sep 17 00:00:00 2001
From: James Knight <james.d.knight@live.com>
Date: Thu, 25 Jul 2024 00:04:51 -0400
Subject: [PATCH 4/5] tox: default run mypy

Attempt to improve static type checks by adding mypy to the default
environment set.

Signed-off-by: James Knight <james.d.knight@live.com>
---
 tox.ini | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tox.ini b/tox.ini
index a58c4afc..9a003adf 100644
--- a/tox.ini
+++ b/tox.ini
@@ -4,6 +4,7 @@ envlist =
     pylint
     py38-sphinx{70,71}
     py{39,310,311,312}-sphinx{70,71,72,73,74}
+    mypy
 
 [testenv]
 deps =

From a478c6c942f43bc72ef4be8befc53e04885459ec Mon Sep 17 00:00:00 2001
From: James Knight <james.d.knight@live.com>
Date: Thu, 25 Jul 2024 00:05:46 -0400
Subject: [PATCH 5/5] workflows: add an mypy environment run

Adding a job dedicated to running mypy checks.

Signed-off-by: James Knight <james.d.knight@live.com>
---
 .github/workflows/build.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 559f0eae..054a38ba 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -67,10 +67,11 @@ jobs:
             - { os:   macos-latest, python: "3.12", toxenv: py312-sphinx74, cache: ~/Library/Caches/pip }
             - { os: windows-latest, python: "3.12", toxenv: py312-sphinx74, cache: ~\AppData\Local\pip\Cache }
 
-            # linting
+            # linting/other
             #  - any OS, using most recent interpreter
             - { os: ubuntu-latest, python: "3.12", toxenv:   ruff, cache: ~/.cache/pip }
             - { os: ubuntu-latest, python: "3.12", toxenv: pylint, cache: ~/.cache/pip }
+            - { os: ubuntu-latest, python: "3.12", toxenv:   mypy, cache: ~/.cache/pip }
 
     steps:
     - uses: actions/checkout@v4