fix(workflows/lint): fix docs dependency resolving

Author: XuehaiPan

docs/requirements.txt

@@ -1,6 +1,6 @@
 --requirement ../requirements.txt
 
-sphinx
+sphinx ~= 8.0
 sphinx-autoapi
 sphinx-autobuild
 sphinx-autodoc-typehints

include/optree/pymacros.h

@@ -29,6 +29,9 @@ limitations under the License.
 #    error "pybind11 2.12.0 or newer is required."
 #endif
 
+// NOLINTNEXTLINE[bugprone-macro-parentheses]
+#define NONZERO_OR_EMPTY(MACRO) ((MACRO + 0 != 0) || (0 - MACRO - 1 >= 0))
+
 namespace py = pybind11;
 
 #if !defined(Py_ALWAYS_INLINE)
@@ -83,6 +86,9 @@ Py_Declare_ID(__qualname__);       // type.__qualname__
 Py_Declare_ID(__name__);           // type.__name__
 Py_Declare_ID(sort);               // list.sort
 Py_Declare_ID(copy);               // dict.copy
+Py_Declare_ID(OrderedDict);        // OrderedDict
+Py_Declare_ID(defaultdict);        // defaultdict
+Py_Declare_ID(deque);              // deque
 Py_Declare_ID(default_factory);    // defaultdict.default_factory
 Py_Declare_ID(maxlen);             // deque.maxlen
 Py_Declare_ID(_fields);            // namedtuple._fields
@@ -91,6 +97,3 @@ Py_Declare_ID(_asdict);            // namedtuple._asdict
 Py_Declare_ID(n_fields);           // structseq.n_fields
 Py_Declare_ID(n_sequence_fields);  // structseq.n_sequence_fields
 Py_Declare_ID(n_unnamed_fields);   // structseq.n_unnamed_fields
-
-// NOLINTNEXTLINE[bugprone-macro-parentheses]
-#define NONZERO_OR_EMPTY(MACRO) ((MACRO + 0 != 0) || (0 - MACRO - 1 >= 0))

include/optree/registry.h

@@ -98,17 +98,18 @@ class PyTreeTypeRegistry {
 
     using RegistrationPtr = std::shared_ptr<const Registration>;
 
-    // Register a new custom type. Objects of `cls` will be treated as container node types in
+    // Register a new custom type. Objects of type `cls` will be treated as container node types in
     // PyTrees.
     static void Register(const py::object &cls,
                          const py::function &flatten_func,
                          const py::function &unflatten_func,
                          const py::object &path_entry_type,
                          const std::string &registry_namespace = "");
 
+    // Unregister a previously registered custom type.
     static void Unregister(const py::object &cls, const std::string &registry_namespace = "");
 
-    // Find the custom type registration for `type`. Returns nullptr if none exists.
+    // Find the custom type registration for `type`. Return nullptr if none exists.
     template <bool NoneIsLeaf>
     [[nodiscard]] static RegistrationPtr Lookup(const py::object &cls,
                                                 const std::string &registry_namespace);
@@ -136,13 +137,18 @@ class PyTreeTypeRegistry {
     [[nodiscard]] static RegistrationPtr UnregisterImpl(const py::object &cls,
                                                         const std::string &registry_namespace);
 
-    // Clear the registry on cleanup.
+    // Clear the registry on cleanup for the current interpreter.
     static void Clear();
 
-    std::unordered_map<py::handle, RegistrationPtr> m_registrations{};
-    std::unordered_map<std::pair<std::string, py::handle>, RegistrationPtr> m_named_registrations{};
+    using RegistrationsMap = std::unordered_map<py::handle, RegistrationPtr>;
+    using NamedRegistrationsMap =
+        std::unordered_map<std::pair<std::string, py::handle>, RegistrationPtr>;
+    using BuiltinsTypesSet = std::unordered_set<py::handle>;
 
-    static inline std::unordered_set<py::handle> sm_builtins_types{};
+    RegistrationsMap m_registrations{};
+    NamedRegistrationsMap m_named_registrations{};
+
+    static inline BuiltinsTypesSet sm_builtins_types{};
     static inline read_write_mutex sm_mutex{};
 };
 

include/optree/synchronization.h

@@ -60,7 +60,7 @@ using scoped_lock = std::scoped_lock<mutex>;
 using scoped_recursive_lock = std::scoped_lock<recursive_mutex>;
 
 #if (defined(__APPLE__) /* header <shared_mutex> is not available on macOS build target */ &&      \
-     PY_VERSION_HEX < /* Python 3.12.0 */ 0x030C00F0)
+     PY_VERSION_HEX < 0x030C00F0 /* Python 3.12.0 */)
 
 #    undef HAVE_READ_WRITE_LOCK
 

include/optree/treespec.h

@@ -288,7 +288,7 @@ class PyTreeSpec {
 
 private:
     using RegistrationPtr = PyTreeTypeRegistry::RegistrationPtr;
-    using ThreadedIdentity = std::pair<const optree::PyTreeSpec *, std::thread::id>;
+    using ThreadedIdentity = std::pair<const PyTreeSpec *, std::thread::id>;
 
     struct Node {
         PyTreeKind kind = PyTreeKind::Leaf;
@@ -333,16 +333,16 @@ class PyTreeSpec {
     // The registry namespace used to resolve the custom pytree node types.
     std::string m_namespace{};
 
-    // Helper that returns the string representation of a node kind.
+    // Return the string representation of a node kind.
     [[nodiscard]] static std::string NodeKindToString(const Node &node);
 
-    // Helper that manufactures an instance of a node given its children.
+    // Manufacture an instance of a node given its children.
     [[nodiscard]] static py::object MakeNode(
         const Node &node,
         const py::object children[],  // NOLINT[hicpp-avoid-c-arrays]
         const size_t &num_children);
 
-    // Helper that identifies the path entry class for a node.
+    // Identify the path entry class for a node.
     [[nodiscard]] static py::object GetPathEntryType(const Node &node);
 
     // Recursive helper used to implement Flatten().

pyproject.toml

@@ -81,7 +81,7 @@ test = [
     "typing-extensions == 4.12.0; python_version >= '3.13' and platform_system == 'Windows'",
 ]
 docs = [
-    "sphinx",
+    "sphinx ~= 8.0",
     "sphinx-autoapi",
     "sphinx-autobuild",
     "sphinx-autodoc-typehints",

src/optree.cpp

@@ -52,9 +52,6 @@ void BuildModule(py::module_ &mod) {  // NOLINT[runtime/references]
                 std::string(__FILE_RELPATH_FROM_PROJECT_ROOT__) + ")";
     mod.attr("Py_TPFLAGS_BASETYPE") = py::int_(Py_TPFLAGS_BASETYPE);
 
-    // NOLINTNEXTLINE[bugprone-macro-parentheses]
-#define NONZERO_OR_EMPTY(MACRO) ((MACRO + 0 != 0) || (0 - MACRO - 1 >= 0))
-
     // Meta information during build
     py::dict BUILDTIME_METADATA{};
     BUILDTIME_METADATA["PY_VERSION"] = py::str(PY_VERSION);
@@ -99,8 +96,6 @@ void BuildModule(py::module_ &mod) {  // NOLINT[runtime/references]
     BUILDTIME_METADATA["GLIBCXX_USE_CXX11_ABI"] = py::bool_(false);
 #endif
 
-#undef NONZERO_OR_EMPTY
-
     mod.attr("BUILDTIME_METADATA") = std::move(BUILDTIME_METADATA);
     py::exec(
         R"py(
@@ -156,7 +151,7 @@ void BuildModule(py::module_ &mod) {  // NOLINT[runtime/references]
              py::arg("namespace") = "")
         .def("flatten",
              &PyTreeSpec::Flatten,
-             "Flattens a pytree.",
+             "Flatten a pytree.",
              py::arg("tree"),
              py::pos_only(),
              py::arg("leaf_predicate") = std::nullopt,
@@ -528,10 +523,13 @@ void BuildModule(py::module_ &mod) {  // NOLINT[runtime/references]
 
 }  // namespace optree
 
+// NOLINTBEGIN[cppcoreguidelines-pro-bounds-pointer-arithmetic,cppcoreguidelines-pro-type-vararg]
 #if PYBIND11_VERSION_HEX >= 0x020D00F0  // pybind11 2.13.0
-// NOLINTNEXTLINE[cppcoreguidelines-pro-bounds-pointer-arithmetic,cppcoreguidelines-pro-type-vararg]
-PYBIND11_MODULE(_C, mod, py::mod_gil_not_used()) { optree::BuildModule(mod); }
+PYBIND11_MODULE(_C, mod, py::mod_gil_not_used())
 #else
-// NOLINTNEXTLINE[cppcoreguidelines-pro-bounds-pointer-arithmetic,cppcoreguidelines-pro-type-vararg]
-PYBIND11_MODULE(_C, mod) { optree::BuildModule(mod); }
+PYBIND11_MODULE(_C, mod)
 #endif
+// NOLINTEND[cppcoreguidelines-pro-bounds-pointer-arithmetic,cppcoreguidelines-pro-type-vararg]
+{
+    optree::BuildModule(mod);
+}

tests/helpers.py

@@ -20,7 +20,9 @@
 import functools
 import gc
 import itertools
+import os
 import platform
+import subprocess
 import sys
 import sysconfig
 import time
@@ -148,6 +150,27 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
+def check_script_in_subprocess(script, /, *, output, env=None, cwd=TEST_ROOT, rerun=1):
+    if env is None:
+        env = os.environ
+    env = {
+        key: value for key, value in env.items() if not key.startswith(('PYTHON', 'PYTEST', 'COV_'))
+    }
+    result = ''
+    for _ in range(rerun):
+        result = subprocess.check_output(
+            [sys.executable, '-Walways', '-Werror', '-c', script],
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding='utf-8',
+            cwd=cwd,
+            env=env,
+        )
+        if output is not None:
+            assert result == output
+    return result
+
+
 MISSING = object()
 
 

tests/test_ops.py

@@ -19,11 +19,9 @@
 import functools
 import itertools
 import operator
-import os
 import pickle
 import platform
 import re
-import subprocess
 import sys
 from collections import OrderedDict, defaultdict, deque
 
@@ -34,7 +32,6 @@
     GLOBAL_NAMESPACE,
     IS_LEAF_FUNCTIONS,
     LEAVES,
-    TEST_ROOT,
     TREE_ACCESSORS,
     TREE_PATHS,
     TREES,
@@ -45,6 +42,7 @@
     Py_DEBUG,
     always,
     assert_equal_type_and_value,
+    check_script_in_subprocess,
     is_list,
     is_none,
     is_tuple,
@@ -60,22 +58,7 @@
 @skipif_android
 @skipif_ios
 def test_import_no_warnings():
-    env = {
-        key: value
-        for key, value in os.environ.items()
-        if not key.startswith(('PYTHON', 'PYTEST', 'COV_'))
-    }
-    assert (
-        subprocess.check_output(
-            [sys.executable, '-Walways', '-Werror', '-c', 'import optree'],
-            stderr=subprocess.STDOUT,
-            text=True,
-            encoding='utf-8',
-            cwd=TEST_ROOT,
-            env=env,
-        )
-        == ''
-    )
+    check_script_in_subprocess('import optree', output='')
 
 
 def test_max_depth():

tests/test_treespec.py

@@ -43,6 +43,7 @@
     MyAnotherDict,
     MyDict,
     Py_DEBUG,
+    check_script_in_subprocess,
     disable_systrace,
     gc_collect,
     parametrize,
@@ -70,11 +71,6 @@ def test_treespec_construct():
     with pytest.raises(TypeError, match=re.escape('No constructor defined!')):
         treespec.__init__()
 
-    env = {
-        key: value
-        for key, value in os.environ.items()
-        if not key.startswith(('PYTHON', 'PYTEST', 'COV_'))
-    }
     script = textwrap.dedent(
         r"""
         import signal
@@ -95,11 +91,7 @@ def test_treespec_construct():
     returncode = 0
     try:
         with tempfile.TemporaryDirectory() as tmpdir:
-            subprocess.check_call(
-                [sys.executable, '-Walways', '-Werror', '-c', script],
-                cwd=tmpdir,
-                env=env,
-            )
+            check_script_in_subprocess(script, cwd=tmpdir, output=None)
     except subprocess.CalledProcessError as ex:
         returncode = abs(ex.returncode)
         if 128 < returncode < 256: