doc: pydocstyle ruff rule (#1975)

* doc: first commit

* doc: modified additional set of files.

* doc: modified more files

* doc: modified more files.

* doc: modified more files

* doc: modified more files.

* doc: modified more files.

* doc: modified more files.

* doc: modified final set of files.

Author: moe-ad

pyproject.toml

@@ -66,7 +66,7 @@ indent-style = "space"
 [tool.ruff.lint]
 select = [
 #   "E",    # pycodestyle, see https://beta.ruff.rs/docs/rules/#pycodestyle-e-w
-#   "D",    # pydocstyle, see https://beta.ruff.rs/docs/rules/#pydocstyle-d
+    "D",    # pydocstyle, see https://beta.ruff.rs/docs/rules/#pydocstyle-d
 #   "F",    # pyflakes, see https://beta.ruff.rs/docs/rules/#pyflakes-f
 #   "I",    # isort, see https://beta.ruff.rs/docs/rules/#isort-i
 #   "N",    # pep8-naming, see https://beta.ruff.rs/docs/rules/#pep8-naming-n

src/ansys/dpf/core/_version.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Version for ansys-dpf-core"""
+"""Version for ansys-dpf-core."""
 
 # Minimal DPF server version supported
 min_server_version = "4.0"

src/ansys/dpf/core/animation.py

@@ -20,6 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+"""Module contains the function for modal animation creation."""
+
 import ansys.dpf.core as dpf
 import numpy as np
 
@@ -34,8 +36,7 @@ def animate_mode(
     **kwargs,
 ):
     # other option: instead of `type` use `min_factor` and `max_factor`.
-
-    """Creates a modal animation based on Fields contained in the FieldsContainer.
+    """Create a modal animation based on Fields contained in the FieldsContainer.
 
     This method creates a movie or a gif based on the time ids of a ``FieldsContainer``.
     For kwargs see pyvista.Plotter.open_movie/add_text/show.

src/ansys/dpf/core/animator.py

@@ -21,7 +21,7 @@
 # SOFTWARE.
 
 """
-Animator
+Animator.
 
 This module contains the DPF animator class.
 
@@ -37,16 +37,15 @@
 
 
 class _InternalAnimatorFactory:
-    """
-    Factory for _InternalAnimator based on the backend."""
+    """Factory for _InternalAnimator based on the backend."""
 
     @staticmethod
     def get_animator_class():
         return _PyVistaAnimator
 
 
 class _PyVistaAnimator(_PyVistaPlotter):
-    """This _InternalAnimator class is based on PyVista"""
+    """An InternalAnimator class based on PyVista."""
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
@@ -190,6 +189,8 @@ def animation():
 
 
 class Animator:
+    """The DPF animator class."""
+
     def __init__(self, workflow=None, **kwargs):
         """
         Create an Animator object.
@@ -228,6 +229,7 @@ def __init__(self, workflow=None, **kwargs):
     def workflow(self) -> core.Workflow:
         """
         Workflow used to generate a Field at each frame of the animation.
+
         By default, the "to_render" Field output will be plotted,
         and the "loop_over" input defines what the animation iterates on.
         Optionally, the workflow can also have a "deform_by" Field output,
@@ -267,7 +269,7 @@ def animate(
         **kwargs,
     ):
         """
-        Animate the workflow of the Animator, using inputs
+        Animate the workflow of the Animator, using inputs.
 
         Parameters
         ----------
@@ -316,6 +318,16 @@ def animate(
 
 
 def scale_factor_to_fc(scale_factor, fc):
+    """Scale the fields being animated by a factor.
+
+    Parameters
+    ----------
+    scale_factor : int, float, list
+        Scale factor to apply to the animated field.
+    fc : FieldsContainer
+        FieldsContainer containing the fields being animated.
+    """
+
     def int_to_field(value, shape, scoping):
         field = core.fields_factory.field_from_array(np.full(shape=shape, fill_value=value))
         field.scoping = scoping

src/ansys/dpf/core/any.py

@@ -21,10 +21,9 @@
 # SOFTWARE.
 
 """
-.. _ref_any:
-
-Any
+Any.
 
+Module containing the wrapper class representing all supported DPF datatypes.
 """
 
 import traceback
@@ -216,7 +215,6 @@ def new_from(obj, server=None):
         any : Any
             Wrapped any type.
         """
-
         inner_server = server if server is not None else obj._server
 
         if not inner_server.meet_version("7.0"):
@@ -295,7 +293,6 @@ def cast(self, output_type=None):
         type
             Original object instance
         """
-
         self._internal_type = output_type if output_type is not None else self._internal_type
 
         type_tuple = self._type_to_new_from_get_as_method(self._internal_type)
@@ -316,6 +313,7 @@ def cast(self, output_type=None):
         raise TypeError(f"{output_type} is not currently supported by the Any class.")
 
     def __del__(self):
+        """Delete the entry."""
         try:
             if hasattr(self, "_deleter_func"):
                 obj = self._deleter_func[1](self)

src/ansys/dpf/core/available_result.py

@@ -21,8 +21,9 @@
 # SOFTWARE.
 
 """
-AvailableResult
+AvailableResult.
 
+Module contains the class representing the results that an operator can request.
 """
 
 from typing import List
@@ -33,6 +34,8 @@
 
 @unique
 class Homogeneity(Enum):
+    """Enum class listing all possible homogeneity names of results."""
+
     acceleration = 0
     angle = 1
     angular_velocity = 2
@@ -147,6 +150,13 @@ def __init__(self, availableresult):
         self._qualifier_labels = availableresult.qualifier_labels
 
     def __str__(self):
+        """Construct an informal string representation of available result.
+
+        Returns
+        -------
+        str
+            Informal string representation of available result.
+        """
         txt = (
             "DPF Result\n----------\n"
             + self.name
@@ -170,6 +180,13 @@ def __str__(self):
         return txt
 
     def __repr__(self):
+        """Construct a formal string representation of available result.
+
+        Returns
+        -------
+        str
+            Formal string representation of available result.
+        """
         return f"AvailableResult<name={self.name}>"
 
     @property
@@ -257,13 +274,15 @@ def native_scoping_location(self):
 
     @property
     def physical_name(self) -> str:
-        """Name of the result with spaces"""
+        """Name of the result with spaces."""
         return self._physics_name
 
     @property
     def qualifiers(self) -> list:
-        """Returns the list of qualifiers (equivalent to label spaces)
-        available for a given Result. These qualifiers can then be used to request the result
+        """
+        Returns the list of qualifiers (equivalent to label spaces) available for a given Result.
+
+        These qualifiers can then be used to request the result
         on specified locations/properties.
         """
         return self._qualifiers
@@ -329,6 +348,18 @@ def qualifier_combinations(self) -> List[dict]:
 
 
 def available_result_from_name(name) -> AvailableResult:
+    """Create an instance of AvailableResult from a specified results name.
+
+    Parameters
+    ----------
+    name : str
+        Valid property name.
+
+    Returns
+    -------
+    AvailableResult
+        Instance created from specified result name.
+    """
     for key, item in _result_properties.items():
         if item["scripting_name"] == name:
             from types import SimpleNamespace

src/ansys/dpf/core/cache.py

@@ -20,11 +20,14 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+"""Provides for caching evaluated results for faster re-evaluation."""
+
 from typing import NamedTuple
 
 
 def class_handling_cache(cls):
     """Class decorator used to handle cache.
+
     To use it, add a ''_to_cache'' static attribute in the given class.
     This private dictionary should map class getters to their list of setters.
     At initialization, this decorator add a ''_cache'' property to the class.
@@ -53,11 +56,14 @@ def get_handler(mesh):
 
 
 class MethodIdentifier(NamedTuple):
+    """Provides for identifying a method."""
+
     method_name: str
     args: list
     kwargs: dict
 
     def __eq__(self, other):
+        """Compare two methods for equality."""
         if isinstance(other, str):
             return self.method_name == other
         else:
@@ -68,6 +74,7 @@ def __eq__(self, other):
             )
 
     def __hash__(self):
+        """Fetch the hash corresponding to a method."""
         hash = self.method_name.__hash__()
         if self.args:
             hash += self.args.__hash__()
@@ -77,7 +84,8 @@ def __hash__(self):
 
 
 class CacheHandler:
-    """ "Handle cache complexity.
+    """Handle cache complexity.
+
     Is initialized by a class and a dictionary mapping the getters
     which support caching to their setters.
     When the getters of the dictionary are called, their parameters
@@ -112,6 +120,7 @@ def __init__(self, cls, getters_to_setters_dict):
         self.cached = {}
 
     def handle(self, object, func, *args, **kwargs):
+        """Recover data which has already been cached."""
         identifier = MethodIdentifier(func.__name__, args, kwargs)
         if identifier in self.cached:
             return self.cached[identifier]
@@ -128,19 +137,19 @@ def handle(self, object, func, *args, **kwargs):
             return func(object, *args, **kwargs)
 
     def clear(self):
+        """Clear cached data."""
         self.cached = {}
 
 
 def _handle_cache(func):
-    """Calls the cache handler to either recover cached data, either cache the data
-    or clear some cached data if the method is a setter.
+    """Call the cache handler to either recover cached data, either cache the data or clear some cached data if the method is a setter.
 
     .. note::
        The method must be used as a decorator.
     """
 
     def wrapper(self, *args, **kwargs):
-        """Call the original function"""
+        """Call the original function."""
         if hasattr(self, "_cache"):
             return self._cache.handle(self, func, *args, **kwargs)
         else:
@@ -150,15 +159,14 @@ def wrapper(self, *args, **kwargs):
 
 
 def _setter(func):
-    """Add a private attribute to the class (``self._is_set = True``)
-    when a method with this decorator is used.
+    """Add a private attribute to the class (``self._is_set = True``) when a method with this decorator is used.
 
     .. note::
        The method must be used as a decorator.
     """
 
     def wrapper(self, *args, **kwargs):
-        """Call the original function"""
+        """Call the original function."""
         if hasattr(self, "_is_set"):
             self._is_set = True
         else:

src/ansys/dpf/core/check_version.py

@@ -52,8 +52,7 @@ def server_meet_version(required_version, server):
 
 
 def server_meet_version_and_raise(required_version, server, msg=None):
-    """Check if a given server version matches with a required version and raise
-    an exception if it does not match.
+    """Check if a given server version matches with a required version and raise an exception if it does not match.
 
     Parameters
     ----------
@@ -76,7 +75,6 @@ def server_meet_version_and_raise(required_version, server, msg=None):
     bool
         ``True`` when successful, ``False`` when failed.
     """
-
     if not server_meet_version(required_version, server):
         if msg is not None:
             raise dpf_errors.DpfVersionNotSupported(required_version, msg=msg)
@@ -142,8 +140,7 @@ def decorator(func):
 
         @wraps(func)
         def wrapper(self, *args, **kwargs):
-            """Call the original function"""
-
+            """Call the original function."""
             if isinstance(self._server, weakref.ref):
                 server = self._server()
             else:

src/ansys/dpf/core/collection.py

@@ -21,10 +21,7 @@
 # SOFTWARE.
 
 # -*- coding: utf-8 -*-
-"""
-Collection
-
-"""
+"""Module containing the class representing dpf objects organized by label spaces."""
 
 from __future__ import annotations
 from ansys.dpf.core.any import Any
@@ -72,6 +69,7 @@ def __init__(self, collection=None, server=None, entries_type: type = None):
                 self._internal_obj = self._api.collection_of_any_new()
 
     def create_subtype(self, obj_by_copy):
+        """Create dpf instance of any type, which has been cast to its original type."""
         return create_dpf_instance(Any, obj_by_copy, self._server).cast(self.entries_type)
 
     def get_entries(self, label_space):
@@ -123,7 +121,7 @@ def add_entry(self, label_space, entry):
 
 
 def CollectionFactory(subtype, BaseClass=Collection):
-    """Creates classes deriving from Collection at runtime for a given subtype."""
+    """Create classes deriving from Collection at runtime for a given subtype."""
 
     def __init__(self, **kwargs):
         BaseClass.__init__(self, **kwargs)