Docstrings v4

arcade/context.py

@@ -34,15 +34,18 @@ class ArcadeContext(Context):
     This context is normally accessed through :py:attr:`arcade.Window.ctx`.
 
     Args:
-        window: The pyglet window
-        gc_mode: The garbage collection mode for OpenGL objects.
-                 ``auto`` is just what we would expect in python
-                 while ``context_gc`` (default) requires you to call ``Context.gc()``.
-                 The latter can be useful when using multiple threads when
-                 it's not clear what thread will gc the object.
-        gl_api: The OpenGL API to use. By default it's set to ``gl`` which is
-                the standard OpenGL API. If you want to use OpenGL ES you can
-                set it to ``gles``.
+        window:
+            The pyglet window
+        gc_mode:
+            The garbage collection mode for OpenGL objects. ``auto`` is just
+            what we would expect in python while ``context_gc`` (default)
+            requires you to call ``Context.gc()``. The latter can be useful
+            when using multiple threads when it's not clear what thread will
+            gc the object.
+        gl_api:
+            The OpenGL API to use. By default it's set to ``gl`` which is
+            the standard OpenGL API. If you want to use OpenGL ES you can
+            set it to ``gles``.
     """
 
     atlas_size: tuple[int, int] = 512, 512
@@ -352,17 +355,26 @@ def load_program(
             )
 
         Args:
-            vertex_shader (str | Path): Path to the vertex shader.
-            fragment_shader (str | Path, optional): Path to the fragment shader (optional).
-            geometry_shader (str | Path, optional): Path to the geometry shader (optional).
-            tess_control_shader (str | Path, optional): Tessellation Control Shader.
-            tess_evaluation_shader (str | Path, optional): Tessellation Evaluation Shader.
-            common (Iterable[str], optional): Common files to be included in all shaders.
-            defines (dict[str, Any], optional): Substitute `#define` values in the source.
-            varyings (Sequence[str], optional): The name of the out attributes in a
-                transform shader. This is normally not necessary since we auto detect them,
+            vertex_shader:
+                Path to the vertex shader.
+            fragment_shader (optional):
+                Path to the fragment shader (optional).
+            geometry_shader (optional):
+                Path to the geometry shader (optional).
+            tess_control_shader (optional):
+                Tessellation Control Shader.
+            tess_evaluation_shader (optional):
+                Tessellation Evaluation Shader.
+            common (optional):
+                Common files to be included in all shaders.
+            defines (optional):
+                Substitute `#define` values in the source.
+            varyings (optional):
+                The name of the out attributes in a transform shader.
+                This is normally not necessary since we auto detect them,
                 but some more complex out structures we can't detect.
-            varyings_capture_mode (str, optional): The capture mode for transforms.
+            varyings_capture_mode (optional):
+                The capture mode for transforms.
 
                 Based on these settings, the `transform()` method will accept a single
                 buffer or a list of buffers.
@@ -420,8 +432,10 @@ def load_compute_shader(
             ctx.load_compute_shader(":shader:compute/do_work.glsl")
 
         Args:
-            path: Path to texture
-            common (optional): Common sources injected into compute shader
+            path:
+                Path to texture
+            common (optional):
+                Common sources injected into compute shader
         """
         from arcade.resources import resolve
 
@@ -461,12 +475,17 @@ def load_texture(
             )
 
         Args:
-            path: Path to texture
-            flip (bool): Flips the image upside down. Default is ``True``.
-            build_mipmaps (bool): Build mipmaps for the texture. Default is ``False``.
-            internal_format (int, optional): The internal format of the texture. This can be used to
-                override the default internal format when using sRGBA or compressed textures.
-            compressed (bool, optional): If the internal format is a compressed format meaning your
+            path:
+                Path to texture
+            flip:
+                Flips the image upside down. Default is ``True``.
+            build_mipmaps:
+                Build mipmaps for the texture. Default is ``False``.
+            internal_format (optional):
+                The internal format of the texture. This can be used to override
+                the default internal format when using sRGBA or compressed textures.
+            compressed (optional):
+                If the internal format is a compressed format meaning your
                 texture will be compressed by the GPU.
         """
         from arcade.resources import resolve
@@ -502,7 +521,7 @@ def shader_inc(self, source: str) -> str:
 
         Example::
 
-            #include :my_shader:lib/common.glsl
+            #include :my_resource_handle:lib/common.glsl
 
         Args:
             source: The shader source code
@@ -527,11 +546,14 @@ def get_framebuffer_image(
         Shortcut method for reading data from a framebuffer and converting it to a PIL image.
 
         Args:
-            fbo (Framebuffer): Framebuffer to get image from
-            components (int): Number of components to read. Default is 4 (RGBA).
+            fbo:
+                Framebuffer to get image from
+            components:
+                Number of components to read. Default is 4 (RGBA).
                 Valid values are 1, 2, 3, 4.
-            flip (bool): Flip the image upside down. This is useful because OpenGL
-                has the origin at the bottom left corner while PIL has it at the top left.
+            flip:
+                Flip the image upside down. This is useful because OpenGL has the
+                origin at the bottom left corner while PIL has it at the top left.
         """
         mode = "RGBA"[:components]
         image = Image.frombuffer(

arcade/geometry.py

@@ -18,11 +18,11 @@ def are_polygons_intersecting(poly_a: Point2List, poly_b: Point2List) -> bool:
     Check if two polygons intersect.
 
     Args:
-        poly_a (Point2List) : List of points that define the first polygon.
-        poly_b (Point2List): List of points that define the second polygon.
+        poly_a: List of points that define the first polygon.
+        poly_b: List of points that define the second polygon.
 
     Returns:
-        True if polygons intersect, False otherwise
+        ``True`` if polygons intersect, ``False`` otherwise
     """
     # if either are [], they don't intersect
     if not poly_a or not poly_b:
@@ -95,9 +95,9 @@ def get_triangle_orientation(p: Point2, q: Point2, r: Point2) -> int:
       * 2 --> Counterclockwise
 
     Args:
-        p (Point2): Point 1
-        q (Point2): Point 2
-        r (Point2): Point 3
+        p: Point 1
+        q: Point 2
+        r: Point 3
 
     Returns:
         int: 0, 1, or 2 depending on the orientation
@@ -118,13 +118,13 @@ def are_lines_intersecting(p1: Point2, q1: Point2, p2: Point2, q2: Point2) -> bo
     returns true if the two lines intersect.
 
     Args:
-        p1 (Point2): Point 1
-        q1 (Point2): Point 2
-        p2 (Point2): Point 3
-        q2 (Point2): Point 4
+        p1: Point 1
+        q1: Point 2
+        p2: Point 3
+        q2: Point 4
 
     Returns:
-        bool: True or false depending if lines intersect
+        bool: ``True`` or ``False`` depending if lines intersect
     """
     o1 = get_triangle_orientation(p1, q1, p2)
     o2 = get_triangle_orientation(p1, q1, q2)
@@ -160,12 +160,12 @@ def is_point_in_polygon(x: float, y: float, polygon: Point2List) -> bool:
     Checks if a point is inside a polygon of three or more points.
 
     Args:
-        x (float): X coordinate of point
-        y (float): Y coordinate of point
-        polygon (Point2List): List of points that define the polygon.
+        x: X coordinate of point
+        y: Y coordinate of point
+        polygon: List of points that define the polygon.
 
     Returns:
-        bool: True or false depending if point is inside polygon
+        bool: ``True`` or ``False`` depending if point is inside polygon
     """
     p = x, y
     n = len(polygon)

arcade/joysticks.py

@@ -11,18 +11,12 @@ def get_joysticks() -> list[Joystick]:
     Get a list of all the game controllers
 
     This is an alias of :func:`get_game_controllers`, which is better worded.
-
-    Returns:
-        List of game controllers
     """
     return pyglet.input.get_joysticks()  # type: ignore  # pending https://github.com/pyglet/pyglet/issues/842
 
 
 def get_game_controllers() -> list[Joystick]:
     """
     Get a list of all the game controllers
-
-    Returns:
-        List of game controllers
     """
     return get_joysticks()

arcade/math.py

@@ -42,8 +42,6 @@ def clamp(a, low: float, high: float) -> float:
         a (float): The number to clamp
         low (float): The lower bound
         high (float): The upper bound
-    Returns:
-        float: The clamped number
     """
     return high if a > high else max(a, low)
 
@@ -59,8 +57,6 @@ def lerp(v1: AsFloat, v2: AsFloat, u: float) -> float:
         v1 (float): The first value
         v2 (float): The second value
         u (float): The interpolation value `(0.0 to 1.0)`
-    Returns:
-        float: The interpolated value
     """
     return v1 + ((v2 - v1) * u)
 
@@ -73,8 +69,6 @@ def lerp_2d(v1: V_2D, v2: V_2D, u: float) -> tuple[float, float]:
         v1 (tuple[float, float]): The first point
         v2 (tuple[float, float]): The second point
         u (float): The interpolation value `(0.0 to 1.0)`
-    Returns:
-        tuple[float, float]: The interpolated 2D point
     """
     return (lerp(v1[0], v2[0], u), lerp(v1[1], v2[1], u))
 
@@ -87,8 +81,6 @@ def lerp_3d(v1: V_3D, v2: V_3D, u: float) -> tuple[float, float, float]:
         v1 (tuple[float, float, float]): The first point
         v2 (tuple[float, float, float]): The second point
         u (float): The interpolation value `(0.0 to 1.0)`
-    Returns:
-        tuple[float, float, float]: The interpolated 3D point
     """
     return (lerp(v1[0], v2[0], u), lerp(v1[1], v2[1], u), lerp(v1[2], v2[2], u))
 
@@ -102,9 +94,6 @@ def lerp_angle(start_angle: float, end_angle: float, u: float) -> float:
         start_angle (float): The starting angle
         end_angle (float): The ending angle
         u (float): The interpolation value (0.0 to 1.0)
-
-    Returns:
-        float: The interpolated angle
     """
     start_angle %= 360
     end_angle %= 360
@@ -124,8 +113,6 @@ def rand_in_rect(rect: Rect) -> Point2:
 
     Args:
         rect (Rect): The rectangle to calculate the point in.
-    Returns:
-        Point2: The random point in the rectangle.
     """
     return (
         random.uniform(rect.left, rect.right),
@@ -146,8 +133,6 @@ def rand_in_circle(center: Point2, radius: float) -> Point2:
     Args:
         center (Point2): The center of the circle
         radius (float): The radius of the circle
-    Returns:
-        Point2: A random point in the circle
     """
     # random angle
     angle = 2 * math.pi * random.random()
@@ -167,8 +152,6 @@ def rand_on_circle(center: Point2, radius: float) -> Point2:
     Args:
         center (Point2): The center of the circle
         radius (float): The radius of the circle
-    Returns:
-        Point2: A random point on the circle
     """
     angle = 2 * math.pi * random.random()
     return (radius * math.cos(angle) + center[0], radius * math.sin(angle) + center[1])
@@ -181,8 +164,6 @@ def rand_on_line(pos1: Point2, pos2: Point2) -> Point:
     Args:
         pos1 (Point2): The first point
         pos2 (Point2): The second point
-    Returns:
-        Point: A random point on the line
     """
     u = random.uniform(0.0, 1.0)
     return lerp_2d(pos1, pos2, u)
@@ -202,8 +183,6 @@ def rand_angle_spread_deg(angle: float, half_angle_spread: float) -> float:
     Args:
         angle (float): The angle to spread from
         half_angle_spread (float): The half angle spread
-    Returns:
-        float: A random angle
     """
     s = random.uniform(-half_angle_spread, half_angle_spread)
     return angle + s
@@ -219,8 +198,6 @@ def rand_vec_spread_deg(
         angle (float): The angle to spread from
         half_angle_spread (float): The half angle spread
         length (float): The length of the vector
-    Returns:
-        tuple[float, float]: A random vector
     """
     a = rand_angle_spread_deg(angle, half_angle_spread)
     vel = Vec2.from_polar(a, length)
@@ -239,8 +216,6 @@ def rand_vec_magnitude(
         angle (float): The angle to spread from
         lo_magnitude (float): The lower magnitude
         hi_magnitude (float): The higher magnitude
-    Returns:
-        tuple[float, float]: A random vector
     """
     mag = random.uniform(lo_magnitude, hi_magnitude)
     vel = Vec2.from_polar(angle, mag)
@@ -256,8 +231,6 @@ def get_distance(x1: float, y1: float, x2: float, y2: float) -> float:
         y1 (float): y coordinate of the first point
         x2 (float): x coordinate of the second point
         y2 (float): y coordinate of the second point
-    Returns:
-        float: Distance between the two points
     """
     return math.hypot(x1 - x2, y1 - y2)
 
@@ -278,8 +251,6 @@ def rotate_point(
         cx (float): x value of the center point you want to rotate around
         cy (float): y value of the center point you want to rotate around
         angle_degrees (float): Angle, in degrees, to rotate
-    Returns:
-        tuple[float, float]: Return rotated (x, y) pair
     """
     temp_x = x - cx
     temp_y = y - cy
@@ -307,9 +278,6 @@ def get_angle_degrees(x1: float, y1: float, x2: float, y2: float) -> float:
         y1 (float): y coordinate of the first point
         x2 (float): x coordinate of the second point
         y2 (float): y coordinate of the second point
-
-    Returns:
-        float: Angle in degrees between the two points
     """
     x_diff = x2 - x1
     y_diff = y2 - y1
@@ -325,9 +293,6 @@ def get_angle_radians(x1: float, y1: float, x2: float, y2: float) -> float:
         y1 (float): y coordinate of the first point
         x2 (float): x coordinate of the second point
         y2 (float): y coordinate of the second point
-
-    Returns:
-        float: Angle in radians between the two points
     """
     x_diff = x2 - x1
     y_diff = y2 - y1
@@ -347,10 +312,6 @@ def quaternion_rotation(axis: Point3, vector: Point3, angle: float) -> tuple[flo
         axis (tuple[float, float, float]): The unit length vector that will be rotated around
         vector (tuple[float, float, float]): The 3-dimensional vector to be rotated
         angle (float): The angle in degrees to rotate the vector clock-wise by
-
-    Returns:
-        tuple[float, float, float]: A rotated 3-dimension vector with the same length as
-        the argument vector.
     """
     _rotation_rads = -math.radians(angle)
     p1, p2, p3 = vector