ci(deps): bump ruff from 0.8.2 to 0.8.4 and mypy from v1.13.0 to v1.14.1

- Update ruff version from 0.8.2 to 0.8.4 in .pre-commit-config.yaml
- Update mypy version from v1.13.0 to v1.14.1 in .pre-commit-config.yaml
- Refactor documentation in constructor.py, data.py, functions.py, and representer.py for clarity and consistency

.pre-commit-config.yaml

@@ -17,12 +17,12 @@ repos:
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.8.2
+    rev: v0.8.4
     hooks:
       - id: ruff
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.13.0"
+    rev: "v1.14.1"
     hooks:
       - id: mypy
         args: [--ignore-missing-imports, --config-file, .mypy.ini]

src/jinjyaml/constructor.py

@@ -16,31 +16,31 @@
 class Constructor:
     """Constructor class for :class:`jinja2.Template` YAML tags.
 
-    When parsing YAML string, the class constructs template tags to :class:`.Data` objects.
+    When parsing a YAML string, this class constructs template tags into :class:`.Data` objects.
 
-    Add the constructor to `PyYAML Loader` as below::
+    To add the constructor to a PyYAML loader, use the following code::
 
         import yaml
         import jinjyaml as jy
 
         ctor = jy.Constructor()
 
-        # Attention: tag name starts with "!"
+        # Note: Tag names start with "!"
 
         # Add to default loader
         yaml.add_constructor("!j2", ctor)
         # or: Add to CLoader
         yaml.add_constructor("!j2", ctor, yaml.CLoader)
         # or: Add to SafeLoader
         yaml.add_constructor("!j2", ctor, yaml.SafeLoader)
-        # or: Add to other Loaders ...
+        # or: Add to other loaders...
 
     Attention:
-       - Custom YAML tag starts with ``"!"``.
-         When we invoke ``yaml.add_constructor``,
-         the ``tag`` parameter **MUST** have a single ``"!"`` at the beginning.
-       - Content of the tag **MUST** be text
-    """  # noqa: E501
+       - Custom YAML tags must start with ``"!"``.
+         When invoking ``yaml.add_constructor``,
+         the ``tag`` parameter **must** include a single leading ``"!"``.
+       - The content of the tag **must** be text.
+    """
 
     def __call__(self, loader: Union[_Loader, _CLoader], node: Node) -> Union[Data, Any]:
         if not isinstance(node, ScalarNode):

src/jinjyaml/data.py

@@ -7,7 +7,7 @@
 
 @dataclass(frozen=True)
 class Data:
-    """A `PyYAML` Custom tag stores string source of a :class:`jinja2.Template` object."""
+    """A custom PyYAML tag that stores the string source of a :class:`jinja2.Template` object."""
 
     source: str
-    """Source code of `jinja2.Template` object"""
+    """The source code of the `jinja2.Template` object."""

src/jinjyaml/functions.py

@@ -24,35 +24,34 @@ def extract(
 ) -> Any:
     """Recursively render and parse template tag objects in a YAML document tree.
 
-    Args:
-        obj: An object that may contain :class:`.Data` instances, such as a list or dictionary.
-
-            It can be one of the following:
-
-            * A mapping or sequence object returned by a `PyYAML Loader`.
-
-                In this case, the function performs the following steps:
-
-                1. Recursively searches inside ``obj`` for :class:`.Data` objects.
-                2. Renders the :attr:`.Data.source` attribute as a string source for a :class:`jinja2.Template` for each found :class:`.Data` object.
-                3. Parses the rendered string using the same `PyYAML Loader` that loaded ``obj``.
-                4. Returns the entire ``obj`` with :class:`.Data` objects replaced by their corresponding parsed Python objects.
+    This function processes an object that may contain :class:`.Data` instances, such as lists or dictionaries.
+    It can handle the following types of input:
 
-            * A single :class:`.Data` object.
+    - A mapping or sequence object returned by a `PyYAML Loader`:
+        1. Recursively searches for :class:`.Data` objects within ``obj``.
+        2. Renders the :attr:`.Data.source` attribute as a string source for a :class:`jinja2.Template`.
+        3. Parses the rendered string using the same `PyYAML Loader` that loaded ``obj``.
+        4. Returns the entire ``obj`` with :class:`.Data` objects replaced by their corresponding parsed Python objects.
 
-                In this case, the function performs the following steps:
+    - A single :class:`.Data` object:
+        1. Renders its :attr:`.Data.source` attribute as a string source for a :class:`jinja2.Template`.
+        2. Parses the rendered string using the same `PyYAML Loader` that loaded ``obj``.
+        3. Returns the parsed Python object.
 
-                1. Renders its :meth:`.Data.source` attribute as a string source for a :class:`jinja2.Template`.
-                2. Parses the rendered string using the same `PyYAML Loader` that loaded ``obj``.
-                3. Returns the parsed Python object.
+    - Other scalar objects returned by a `PyYAML Loader`:
+        Directly returns ``obj`` without any changes.
 
-            * Other scalar objects returned by a `PyYAML Loader`.
-
-                In this case, the function directly returns ``obj`` without any changes.
+    Note:
+        - ``obj`` must be a mutable :class:`dict` or :class:`list`-like object if ``inplace`` is :data:`True`.
+        - If ``obj`` is an instance of :class:`.Data`, it will **not** be changed, even if ``inplace`` is set to :data:`True`.
+            However, nested :class:`.Data` objects within mutable structures will still be replaced.
+        - The return value is always the parsed result.
 
+    Args:
+        obj: An object that may contain :class:`.Data` instances.
         loader_type: The `PyYAML Loader` used to load ``obj``.
-        env: The :class:`jinja2.Environment` for template rendering.
-        context: A dictionary of variable name-value pairs for :mod:`jinja2` template rendering.
+        env: The :class:`jinja2.Environment` for template rendering (optional).
+        context: A dictionary of variable name-value pairs for :mod:`jinja2` template rendering (optional).
 
         inplace: Whether to perform an in-place replacement of :class:`.Data` objects within ``obj``.
 
@@ -62,14 +61,6 @@ def extract(
             - When :data:`False` (default):
               Renders and parses every :class:`.Data` object with its corresponding parsed Python object without modifying the passed-in object.
 
-            Note:
-                ``obj`` must be a mutable :class:`dict` or :class:`list`-like object if ``inplace`` is :data:`True`.
-
-            Note:
-                If the passed-in ``obj`` argument is an instance of :class:`.Data`, it will **not** be changed, even if ``inplace`` is set to :data:`True`.
-                However, if there is a mutable :class:`dict` or :class:`list`-like object parsed by the YAML loader that contains nested :class:`.Data` objects, those nested parts will be replaced.
-                The return value is always the parsed result.
-
     Returns:
         The final parsed and extracted Python object.
     """

src/jinjyaml/representer.py

@@ -15,15 +15,18 @@
 class Representer:
     """Representer for :class:`jinja2.Template` tags.
 
-    When dumping an object into YAML string,
-    convert :class:`.Data` to string.
+    When dumping an object into a YAML string, this class converts :class:`.Data` objects to their string representation.
 
-    Add the representer to `PyYAML Dumper` as below::
+    To add the representer to a PyYAML dumper, use the following code::
 
-        representer = jinjyaml.Representer("j2")  # No "!" here !!!
+        representer = jinjyaml.Representer("j2")  # Note: No "!" here!
         yaml.add_representer(Node, representer)
 
-    """  # noqa: E501
+    Attention:
+        - The tag name passed to the `Representer` constructor **MUST NOT** include the leading "!".
+          This is because PyYAML automatically adds the "!" when registering the representer.
+        - Ensure that `Node` is the correct type for the objects you want to represent.
+    """
 
     tag: str
     """YAML tag name for include statement
@@ -35,6 +38,6 @@ class Representer:
     """
 
     def __call__(self, dumper: Dumper, data: Data) -> ScalarNode:
-        if not isinstance(data, Data):  # pragma: no cover
+        if not isinstance(data, Data):
             raise TypeError(f"{type(data)}")
         return dumper.represent_scalar(f"!{self.tag}", data.source)