Texture related docstring improvements (#2299)

* cache

* texture related docstrings

* Remove Self

* close inline literal

* uv_data

* atlas docstrings

* hitbox

Author: einarf

arcade/cache/__init__.py

@@ -16,8 +16,9 @@ def crate_str_from_values(*args, sep: str = "_") -> str:
         >> crate_str_from_list("blue", 5)
         "blue_5"
 
-    :param params: List of parameters to create a string from.
-    :param sep: Separator to use between parameters.
+    Args:
+        params: List of parameters to create a string from.
+        sep: Separator to use between parameters.
     """
     return sep.join([str(x) for x in args])
 
@@ -32,8 +33,9 @@ def crate_str_from_list(entries: list[Any], sep: str = "_") -> str:
         >> crate_str_from_list(entries)
         "blue_5"
 
-    :param entries: List of parameters to create a string from.
-    :param sep: Separator to use between parameters.
+    Args:
+        entries: List of parameters to create a string from.
+        sep: Separator to use between parameters.
     """
     return crate_str_from_values(*entries, sep=sep)
 

arcade/cache/hit_box.py

@@ -58,8 +58,11 @@ def get(self, name_or_texture: str | Texture) -> Point2List | None:
             # Get a cache entry by string
             points = cache.get("hash|(0, 1, 2, 3)|simple|")
 
-        :param keys: List of keys to use for the cache entry
-        :param hit_box_algorithm: The hit box algorithm used
+        Args:
+            keys:
+                The texture or cache name to get the hit box for
+            hit_box_algorithm:
+                The hit box algorithm used
         """
         from arcade import Texture
 
@@ -81,8 +84,11 @@ def put(self, name_or_texture: str | Texture, points: Point2List) -> None:
             # Cache with custom string
             cache.put("my_custom_points", points)
 
-        :param keys: List of keys to use for the cache entry
-        :param points: The hit box points
+        Args:
+            keys:
+                The texture or cache name to store the hit box for
+            points:
+                The hit box points
         """
         from arcade import Texture
 
@@ -105,6 +111,9 @@ def load(self, path: str | Path) -> None:
         entries and can therefore be called multiple times to populate it.
 
         if the file extension is ".gz" the file will be compressed.
+
+        Args:
+            path: The path to the json file to load
         """
         path = resolve(path)
         if path.suffix == ".gz":
@@ -126,8 +135,11 @@ def save(self, path: Path, indent: int = 0) -> None:
 
         if the file extension is ".gz" the file will be compressed.
 
-        :param path: The path to save the cache to
-        :param indent: The indentation level for the json file
+        Args:
+            path:
+                The path to save the cache to
+            indent:
+                The indentation level for the json file
         """
         if indent == 0:
             data_str = json.dumps(self._entries)
@@ -143,9 +155,7 @@ def save(self, path: Path, indent: int = 0) -> None:
             fd.write(data)
 
     def flush(self) -> None:
-        """
-        Clear the cache.
-        """
+        """Clear the cache."""
         self._entries.clear()
 
     def __repr__(self) -> str:

arcade/cache/image_data.py

@@ -32,8 +32,9 @@ def put(self, name: str, image: "ImageData"):
         An entry can only be cached as either strong or weak, not both.
         If and existing entry is found, it will be replaced.
 
-        :param name: Name of the image
-        :param image: ImageData object
+        Args:
+            name: Name of the image
+            image: ImageData object
         """
         from arcade.texture import ImageData
 
@@ -46,17 +47,22 @@ def get(self, name: str) -> ImageData | None:
         """
         Attempts to retrieve an entry from the cache.
 
-        :param name: Name of the image
-        :return: ImageData object or None if not found
+        Args:
+            name: Name of the image
+        Returns:
+            ImageData instance or ``None`` if not found
         """
         return self._entries.get(name)
 
     def delete(self, name: str, raise_if_not_exist: bool = False) -> None:
         """
         Attempts to delete an entry from the cache.
 
-        :param name: Name of the image
-        :param raise_if_not_exist: If True, raises KeyError if the entry does not exist
+        Args:
+            name:
+                Name of the image
+            raise_if_not_exist:
+                If ``True``, raises ``KeyError`` if the entry does not exist
         """
         try:
             del self._entries[name]

arcade/cache/texture.py

@@ -19,25 +19,59 @@ def __init__(self):
         self._entries: dict[str, Texture] = {}
 
     def put(self, name: str, texture: Texture) -> None:
+        """
+        Add a texture to the cache.
+
+        Args:
+            name:
+                The cache name of the texture
+            texture:
+                The texture to add
+        """
         self._entries[name] = texture
 
     def get(self, name: str) -> Texture | None:
+        """
+        Get a texture from the cache by cache name.
+
+        Args:
+            name:
+                The cache name of the texture
+        Returns:
+            The texture if found, otherwise ``None``
+        """
         return self._entries.get(name)
 
     def delete(self, name: str, raise_if_not_exist: bool = True) -> None:
+        """
+        Delete a texture from the cache by cache name.
+
+        Args:
+            name:
+                The cache name of the texture
+            raise_if_not_exist:
+                If ``True``, raises ``KeyError`` if the entry does not exist
+        """
         try:
             del self._entries[name]
         except KeyError:
             if raise_if_not_exist:
                 raise
 
     def delete_by_value(self, texture: "Texture") -> None:
+        """
+        Delete a texture from the cache by texture instance.
+
+        Args:
+            texture: The texture instance to delete
+        """
         for name, value in self._entries.items():
             if value is texture:
                 del self._entries[name]
                 return
 
     def flush(self) -> None:
+        """Clear the cache"""
         self._entries.clear()
 
     def __len__(self) -> int:
@@ -72,7 +106,8 @@ def put(self, texture: "Texture") -> None:
         and file path are correctly set on the texture before adding it to
         the cache.
 
-        :param texture: The texture to add
+        Args:
+            texture: The texture to add
         """
         self._entries.put(texture.cache_name, texture)
 
@@ -87,18 +122,24 @@ def get(self, name: str) -> Texture | None:
         """
         Get a texture from the cache by cache name
 
-        :param name: The cache name of the texture
-        :return: The texture if found, otherwise None
+        Args:
+            name: The cache name of the texture
+        Returns:
+            The texture if found, otherwise ``None``
         """
         return self._entries.get(name)
 
     def get_with_config(self, hash: str, hit_box_algorithm: "HitBoxAlgorithm") -> Texture | None:
         """
         Attempts to find a texture with a specific configuration.
 
-        :param hash: The image hash
-        :param hit_box_algorithm: The hit box algorithm to search for
-        :return: The texture if found, otherwise None
+        Args:
+            hash:
+                The image hash
+            hit_box_algorithm:
+                The hit box algorithm to search for
+        Returns:
+            The texture if found, otherwise ``None``
         """
         from arcade import Texture
 
@@ -116,7 +157,9 @@ def get_texture_by_filepath(
         """
         Get a texture from the cache by file path and crop values.
 
-        :param file_path: The path to the file the texture was loaded from
+        Args:
+            file_path: The path to the file the texture was loaded from
+            crop: The crop values used when creating the texture
         """
         from arcade import Texture
 
@@ -127,8 +170,11 @@ def delete(self, texture_or_name: Texture | str, raise_if_not_exist: bool = Fals
         """
         Delete a texture from the cache by cache name.
 
-        :param texture_or_name: The texture or cache name to delete
-        :param ignore_error: If True, ignore errors when deleting
+        Args:
+            texture_or_name:
+                The texture or cache name to delete
+            raise_if_not_exist:
+                If ``True``, ignore errors when deleting
         """
         if isinstance(texture_or_name, Texture):
             texture = texture_or_name

arcade/hitbox/__init__.py

@@ -25,9 +25,8 @@ def calculate_hit_box_points_simple(image: Image, *args) -> Point2List:
     Given an RGBA image, this returns points that make up a hit box around it. Attempts
     to trim out transparent pixels.
 
-    :param image: Image get hit box from.
-
-    :Returns: List of points
+    Args:
+        image: Image get hit box from.
     """
     return algo_simple.calculate(image)
 
@@ -40,11 +39,12 @@ def calculate_hit_box_points_detailed(
     Given an RGBA image, this returns points that make up a hit box around it. Attempts
     to trim out transparent pixels.
 
-    :param image: Image get hit box from.
-    :param hit_box_detail: How detailed to make the hit box. There's a
-                               trade-off in number of points vs. accuracy.
-
-    :Returns: List of points
+    Args:
+        image:
+            Image get hit box from.
+        hit_box_detail:
+            How detailed to make the hit box. There's a
+            trade-off in number of points vs. accuracy.
     """
     return algo_detailed.calculate(image, detail=hit_box_detail)
 

arcade/hitbox/base.py

@@ -49,19 +49,25 @@ def calculate(self, image: Image, **kwargs) -> Point2List:
                      when initialized, subclasses use them to alter how
                      a specific instance handles image data by default.
 
-        :param image: The image to calculate hitbox points for
-        :param kwargs: keyword arguments
-        :return: A list of hit box points.
+        Args:
+            image:
+                The image to calculate hitbox points for
+            kwargs:
+                keyword arguments
         """
         raise NotImplementedError
 
     def __call__(self, *args: Any, **kwds: Any) -> Self:
         """
         Shorthand allowing any instance to be used identically to the base type.
 
-        :param args: The same positional arguments as `__init__`
-        :param kwds: The same keyword arguments as `__init__`
-        :return: A new HitBoxAlgorithm instance
+        Args:
+            args:
+                The same positional arguments as `__init__`
+           kwds:
+                The same keyword arguments as `__init__`
+        Returns:
+            A new HitBoxAlgorithm instance
         """
         return self.__class__(*args, **kwds)  # type: ignore
 
@@ -72,8 +78,8 @@ def create_bounding_box(self, image: Image) -> Point2List:
         doesn't manage to figure out any reasonable points for
         an image.
 
-        :param image: The image to create a bounding box for.
-        :return: A tuple of hit box points.
+        Args:
+            image: The image to create a bounding box for.
         """
         size = image.size
         return (
@@ -93,10 +99,13 @@ class HitBox:
     use :py:meth:`.create_rotatable` to create an instance of
     :py:class:`RotatableHitBox`.
 
-    :param points: The unmodified points bounding the hit box
-    :param position: The center around which the points will be offset
-    :param scale: The X and Y scaling factors to use when offsetting the
-        points
+    Args:
+        points:
+            The unmodified points bounding the hit box
+        position:
+            The center around which the points will be offset
+        scale:
+            The X and Y scaling factors to use when offsetting the points
     """
 
     def __init__(
@@ -128,7 +137,6 @@ def points(self) -> Point2List:
     def position(self) -> Point2:
         """
         The center point used to offset the final adjusted positions.
-        :return:
         """
         return self._position
 
@@ -199,11 +207,11 @@ def create_rotatable(
         Create a rotatable instance of this hit box.
 
         The internal ``PointList`` is transferred directly instead of
-        deepcopied, so care should be taken if using a mutable internal
+        deep copied, so care should be taken if using a mutable internal
         representation.
 
-        :param angle: The angle to rotate points by (0 by default)
-        :return:
+        Args:
+            angle: The angle to rotate points by (0 by default)
         """
         return RotatableHitBox(
             self._points, position=self._position, scale=self._scale, angle=angle
@@ -241,6 +249,16 @@ class RotatableHitBox(HitBox):
 
     Rotation is separated from the basic hitbox because it is much
     slower than offsetting and scaling.
+
+    Args:
+        points:
+            The unmodified points bounding the hit box
+        position:
+            The translation to apply to the points
+        angle:
+            The angle to rotate the points by
+        scale:
+            The X and Y scaling factors
     """
 
     def __init__(
@@ -272,7 +290,6 @@ def get_adjusted_points(self) -> Point2List:
 
         As with :py:meth:`.HitBox.get_adjusted_points`, this method only
         recalculates the adjusted values when necessary.
-        :return:
         """
         if not self._adjusted_cache_dirty:
             return self._adjusted_points