refactor!: enforce naming convention of packages with singular and plural (#209)

Author: XuehaiPan

.pre-commit-config.yaml

@@ -35,7 +35,7 @@ repos:
     hooks:
       - id: cpplint
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.7
+    rev: v0.11.8
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

CHANGELOG.md

@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
--
+- Enforce naming convention of packages with singular and plural: `optree.{accessor,integration}` -> `optree.{accessors,integrations}` by [@XuehaiPan](https://github.com/XuehaiPan) in [#209](https://github.com/metaopt/optree/pull/209).
 
 ### Fixed
 

docs/source/index.rst

@@ -22,7 +22,7 @@ OpTree: Optimized PyTree Utilities
 .. toctree::
     :maxdepth: 2
 
-    integration.rst
+    integrations.rst
 
 License
 -------

docs/source/integration.rst docs/source/integrations.rstdocs/source/integration.rst renamed to docs/source/integrations.rst

@@ -1,10 +1,10 @@
-Integration with Third-Party Libraries
-======================================
+Integrations with Third-Party Libraries
+=======================================
 
 Integration for `JAX <https://github.com/jax-ml/jax>`_
 ------------------------------------------------------
 
-.. currentmodule:: optree.integration.jax
+.. currentmodule:: optree.integrations.jax
 
 .. autosummary::
 
@@ -17,7 +17,7 @@ Integration for `JAX <https://github.com/jax-ml/jax>`_
 Integration for `NumPy <https://github.com/numpy/numpy>`_
 ---------------------------------------------------------
 
-.. currentmodule:: optree.integration.numpy
+.. currentmodule:: optree.integrations.numpy
 
 .. autosummary::
 
@@ -30,7 +30,7 @@ Integration for `NumPy <https://github.com/numpy/numpy>`_
 Integration for `PyTorch <https://github.com/pytorch/pytorch>`_
 ---------------------------------------------------------------
 
-.. currentmodule:: optree.integration.torch
+.. currentmodule:: optree.integrations.torch
 
 .. autosummary::
 

docs/source/spelling_wordlist.txt

@@ -38,6 +38,7 @@ initializer
 inplace
 instantiate
 instantiation
+integrations
 isinstance
 issubclass
 iterable

include/optree/treespec.h

@@ -120,10 +120,10 @@ class PyTreeSpec {
     [[nodiscard]] py::object Unflatten(const py::iterable &leaves) const;
 
     // Flatten a PyTree up to this PyTreeSpec. 'this' must be a tree prefix of the tree-structure of
-    // 'full_tree'.
+    // 'tree'.
     // For example, if we flatten a value [(1, (2, 3)), {"foo": 4}] with a PyTreeSpec([(*, *), *]),
     // the result is the list of leaves [1, (2, 3), {"foo": 4}].
-    [[nodiscard]] py::list FlattenUpTo(const py::object &full_tree) const;
+    [[nodiscard]] py::list FlattenUpTo(const py::object &tree) const;
 
     // Broadcast to a common suffix of this PyTreeSpec and other PyTreeSpec.
     [[nodiscard]] std::unique_ptr<PyTreeSpec> BroadcastToCommonSuffix(
@@ -136,7 +136,7 @@ class PyTreeSpec {
         const std::optional<py::function> &f_leaf = std::nullopt) const;
 
     // Compose two PyTreeSpecs, replacing the leaves of this tree with copies of `inner`.
-    [[nodiscard]] std::unique_ptr<PyTreeSpec> Compose(const PyTreeSpec &inner_treespec) const;
+    [[nodiscard]] std::unique_ptr<PyTreeSpec> Compose(const PyTreeSpec &inner) const;
 
     // Map a function over a PyTree structure, applying `f_leaf(leaf)` to each leaf,
     // and `f_node(node)` to each reconstructed non-leaf node.

optree/_C.pyi

@@ -114,15 +114,15 @@ class PyTreeSpec:
     type: builtins.type | None
     kind: PyTreeKind
     def unflatten(self, leaves: Iterable[T], /) -> PyTree[T]: ...
-    def flatten_up_to(self, full_tree: PyTree[T], /) -> list[PyTree[T]]: ...
+    def flatten_up_to(self, tree: PyTree[T], /) -> list[PyTree[T]]: ...
     def broadcast_to_common_suffix(self, other: Self, /) -> Self: ...
     def transform(
         self,
         /,
         f_node: Callable[[Self], Self] | None = None,
         f_leaf: Callable[[Self], Self] | None = None,
     ) -> Self: ...
-    def compose(self, inner_treespec: Self, /) -> Self: ...
+    def compose(self, inner: Self, /) -> Self: ...
     def traverse(
         self,
         leaves: Iterable[T],

optree/__init__.py

@@ -14,8 +14,8 @@
 # ==============================================================================
 """OpTree: Optimized PyTree Utilities."""
 
-from optree import accessor, dataclasses, functools, integration, pytree, treespec, typing
-from optree.accessor import (
+from optree import accessors, dataclasses, functools, integrations, pytree, treespec, typing
+from optree.accessors import (
     AutoEntry,
     DataclassEntry,
     FlattenedEntry,
@@ -233,3 +233,22 @@
 """Literal constant that treats :data:`None` as a pytree non-leaf node."""
 NONE_IS_LEAF: bool = NONE_IS_LEAF  # literal constant
 """Literal constant that treats :data:`None` as a pytree leaf node."""
+
+
+# pylint: disable-next=fixme
+# TODO: remove this file in version 0.18.0
+def __getattr__(name: str, /) -> object:  # pragma: no cover
+    """Get an attribute from the module."""
+    if name == 'accessor':
+        global accessor  # pylint: disable=global-statement
+
+        import optree.accessor as accessor  # pylint: disable=import-outside-toplevel
+
+        return accessor  # type: ignore[name-defined]
+    if name == 'integration':
+        global integration  # pylint: disable=global-statement
+
+        import optree.integration as integration  # pylint: disable=import-outside-toplevel
+
+        return integration  # type: ignore[name-defined]
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')